Initialise a payment
Creates a pending transaction and returns everything you need to collect it: a generated reference (VPY_TXN_…), an accessCode for checkout calls, and a hosted checkoutUrl.
Call this from your server with your secret key each time a customer is about to pay. Redirect the customer to checkoutUrl, or keep accessCode and build your own pay screen with the Checkout endpoints. Never send the secret key to the browser.
Fees. The response shows what the customer would pay on each channel. cardTotal and transferTotal include the fee when the customer bears it. When merchantBearsCost is true the customer pays exactly amount and the fee is deducted from what you receive. The default comes from your payment settings, and you can override it per payment.
Splitting. Add distribution to allocate part of the payment to services you set up in the dashboard. Keys are service keys, values are absolute amounts, and their total must not exceed amount. The unallocated remainder settles to your primary settlement account. The response echoes the distribution that was applied. A distribution that names a missing or disabled service is rejected with INVALID_SPLIT_AMOUNT and nothing is created.
After initialise. Treat the payment as unpaid until verify says otherwise. The callbackUrl receives status, reference, amount and currency as query parameters, but that is a browser signal and can be forged or lost.
Authorizations
Your secret key. sk_test_… on the sandbox, sk_live_… on live. Server-side only.
Copy it from Settings → Developers in the merchant dashboard.
Authorization: Bearer with the same value is also accepted.
Body
The body of an initialise request.
What you are collecting, as a decimal string in major units. "100.00" is one hundred naira. Never kobo and never a formatted value. When the customer bears the fee it is added on top, so this is the amount you expect to receive.
^\d+(\.\d{1,2})?$"100.00"
ISO 4217 currency code. NGN is the supported currency.
The customer's email, used on receipts. Required for pay with transfer, so send it whenever you have it.
Shown on the hosted checkout page.
Where the browser returns after checkout, with status, reference, amount and currency as query parameters. Use an HTTPS URL on your own domain. The callback is a signal only, so confirm with verify before you fulfil.
Free text shown on checkout, such as "Order 12345".
Any JSON object. Stored with the payment and returned on verify. Use it to carry your own order or customer ID.
Allocates part of this payment to services you configured in the merchant dashboard. Each key is a service key and each value is an absolute amount in the same major unit as amount (a number with up to two decimal places).
The total of all values must not exceed amount. You may allocate less than the whole, and often will. Each service's allocation is divided among its sub-accounts by its split shares, and everything you do not allocate settles to your primary settlement account.
Every key must be a service that exists in this environment and is enabled and has at least one split. Anything else is rejected with INVALID_SPLIT_AMOUNT and no payment is created. Compute the map on your server. Never take allocation amounts from the browser.
Overrides, for this payment only, who pays the fee. When true the customer pays exactly amount and the fee is deducted from what you receive. When false the fee is added to what the customer pays. Omit it to use your payment settings.