Overview

Every payment starts with initialize. After that you choose how the customer pays.

Redirect

POST /v1/payment/initialize with your secret key.
Redirect the browser to data.checkoutUrl.
The customer picks card or transfer (and any other enabled channel).
We send them to callbackUrl when checkout is done.
Confirm with a webhook and verify.

Custom checkout

Initialize. Keep data.accessCode and data.reference.
For card, start a hosted card session, mount the processor fields, then charge. See Pay with card.
For transfer, request a virtual account and show bank name, account number, and expiry. See Pay with transfer.
Subscribe to GET /v1/payment/checkout/events if the pay page should update live.

Checkout calls after initialize use the access code.

What initialize accepts

Field	Required	Notes
amount	Yes	Major units as a string, `"250.00"`.
currency	No	Defaults to NGN.
email	For transfer	Used on receipts. Required for bank transfer.
customerName	No	Shown on checkout.
callbackUrl	No	Browser return URL after pay.
description	No	Shown on checkout.
metadata	No	JSON object. Echoed on verify.
distribution	No	Map of service key → amount. Sum must not exceed `amount`. Remainder goes to the primary account.
merchantBearsCost	No	Override who pays the fee for this transaction.

Initialize returns data.reference (VPY_TXN_…). Store it on the order.

Callback query string

When checkout finishes, the browser hits your callbackUrl:

https://yourapp.com/paid?status=success&reference=VPY_TXN_…&amount=100.00&currency=NGN

Query	Meaning
`status`	Checkout outcome.
`reference`	Pass this to verify.
`amount`	Amount shown at checkout.
`currency`	Usually `NGN`.
`error`	Present when checkout surfaces a message.

Confirm with verify.

Metadata

{
  "amount": "100.00",
  "email": "customer@email.com",
  "metadata": {
    "orderId": "ORD_12345",
    "customerId": "CUST_67890"
  }
}

metadata is returned on verify.

Split (distribution)

{
  "amount": "100.00",
  "email": "customer@email.com",
  "distribution": { "utility": 70, "logistics": 30 }
}

₦70 goes to the utility group, ₦30 to logistics. Remainder settles to the primary account. The sum must not exceed amount. Verify includes split when a distribution was applied.

Fees

Field	Meaning
`amount`	What you asked to collect.
`cardFee` / `transferFee`	Fee for that channel.
`cardTotal` / `transferTotal`	What the customer pays on that channel when they bear the fee.
`merchantBearsCost`	If true, the customer pays `amount` and the fee comes out of you.

Channels

Initialize echoes channels for the merchant: card, bank_transfer, bank_payment, and ussd. Hosted checkout shows the ones enabled for you.

Get started

Accept payments

Redirect

Custom checkout

What initialize accepts

Callback query string

Metadata

Split (distribution)

Fees

Channels

​Redirect

​Custom checkout

​What initialize accepts

​Callback query string

​Metadata

​Split (distribution)

​Fees

​Channels

Redirect

Custom checkout

What initialize accepts

Callback query string

Metadata

Split (distribution)

Fees

Channels