Accept payments

Every Vestrapay payment starts with one call from your server: initialise. It creates a pending transaction and returns the three things you need to take payment: a reference to track it, an access code to authorise checkout calls, and a checkout URL for the hosted pay page. After that you choose how the customer pays.

Choose how the customer pays

Hosted checkout

Redirect the browser to the checkout URL. Vestrapay renders the pay screen, collects card details in processor-hosted fields, runs 3-D Secure and shows transfer details. Least code, fastest to production.

Custom checkout

Build your own pay screen and call the checkout endpoints with the access code. You control every pixel and every state, and you take on the 3-D Secure and countdown handling.

Hosted checkout

Your server sends POST /v1/payment/initialize with your secret key.
You store data.reference on the order and redirect the browser to data.checkoutUrl.
The customer picks a channel and pays. Hosted checkout handles card entry, 3-D Secure, transfer details, retries and expiry.
Vestrapay sends the browser to your callbackUrl and posts a webhook to your server.
You verify the payment and fulfil the order.

Custom checkout

Initialise as above. Keep data.accessCode and data.reference.
For card, create a hosted card session, mount the processor’s fields, then charge. See Pay with card.
For transfer, request a virtual account and show the bank, account number and countdown. See Pay with transfer.
For pay with bank and USSD, see Other channels.
Optionally subscribe to GET /v1/payment/checkout/events so the pay page updates live.
Confirm with a webhook and verify, exactly as for hosted checkout.

Every checkout call after initialise authenticates with the access code in the x-access-code header, never with the secret key. The access code expires after 60 minutes.

What initialise accepts

Send a JSON body to POST /v1/payment/initialize with your secret key.

Field	Required	Type	Notes
`amount`	Yes	String	Major units as a decimal string, “250.00”. Never kobo.
`currency`	No	String	Defaults to NGN. NGN is the supported currency.
`email`	For transfer	String	Customer email, used on receipts. Required for pay with transfer, so send it whenever you have it.
`customerName`	No	String	Shown on the checkout page.
`callbackUrl`	No	String	Where the browser returns after checkout. Use an HTTPS URL on your own domain.
`description`	No	String	Free text shown on checkout, such as “Order 12345”.
`metadata`	No	Object	Any JSON object. Stored with the payment and returned on verify.
`distribution`	No	Object	Map of service key to amount. Divides the collection across your services. See Distribution.
`merchantBearsCost`	No	Boolean	Overrides, for this payment only, whether you or the customer pays the fee.

A successful call returns HTTP 201 and the session in the data object:

{
  "status": "success",
  "data": {
    "reference": "VPY_TXN_ACME001",
    "accessCode": "a1b2c3d4e5f6a1b2",
    "checkoutUrl": "https://checkout.sandbox.vestrapay.app/a1b2c3d4e5f6a1b2",
    "amount": "100.00",
    "cardFee": "1.50",
    "transferFee": "1.00",
    "cardTotal": "101.50",
    "transferTotal": "101.00",
    "currency": "NGN",
    "merchantBearsCost": false,
    "channels": ["card", "bank_transfer", "bank_payment", "ussd"],
    "status": "pending"
  }
}

When you pass a distribution, the response echoes it back in a distribution property so you can confirm what was applied.

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/initialize \
  -H "x-api-key: $VESTRAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "email": "customer@email.com",
    "customerName": "Jane Doe",
    "callbackUrl": "https://yourapp.com/paid",
    "description": "Order 12345",
    "metadata": { "orderId": "ORD_12345", "customerId": "CUST_67890" }
  }'

const res = await fetch("https://api.sandbox.vestrapay.app/v1/payment/initialize", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VESTRAPAY_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "250.00",
    email: "customer@email.com",
    customerName: "Jane Doe",
    callbackUrl: "https://yourapp.com/paid",
    description: "Order 12345",
    metadata: { orderId: "ORD_12345", customerId: "CUST_67890" },
  }),
});
const { status, data } = await res.json();

import os, requests

res = requests.post(
    "https://api.sandbox.vestrapay.app/v1/payment/initialize",
    headers={"x-api-key": os.environ["VESTRAPAY_SECRET_KEY"]},
    json={
        "amount": "250.00",
        "email": "customer@email.com",
        "customerName": "Jane Doe",
        "callbackUrl": "https://yourapp.com/paid",
        "description": "Order 12345",
        "metadata": {"orderId": "ORD_12345", "customerId": "CUST_67890"},
    },
    timeout=15,
)
payload = res.json()

<?php
$ch = curl_init("https://api.sandbox.vestrapay.app/v1/payment/initialize");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "x-api-key: " . getenv("VESTRAPAY_SECRET_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => "250.00",
    "email" => "customer@email.com",
    "customerName" => "Jane Doe",
    "callbackUrl" => "https://yourapp.com/paid",
    "description" => "Order 12345",
    "metadata" => ["orderId" => "ORD_12345", "customerId" => "CUST_67890"],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$payload = json_decode(curl_exec($ch), true);

The callback query string

When checkout finishes, the customer’s browser is sent to your callback URL with these query parameters added:

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

Query parameter	Meaning
`status`	The outcome checkout is reporting to the browser.
`reference`	The Vestrapay reference. Pass it to verify.
`amount`	The amount shown at checkout.
`currency`	Usually NGN.
`error`	Present only when checkout surfaces a message for the customer.

The callback page is for the customer’s experience: show a receipt, a failure message or a “we are confirming your payment” screen. It is not a trusted signal. Anyone can type a URL into a browser, so never fulfil from these parameters. Call verify from your server with the reference and decide there.

Metadata

Metadata is your own correlation data. Use it to carry whatever you need to find the order again, such as an order ID, a customer ID or a campaign tag.

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

Metadata is stored with the payment and returned unchanged on verify and on the collection record. Keep it small and do not put secrets or card data in it. Because verify returns it, you can rebuild your order context from a reference alone.

Metadata on a payment link is different. On a link it defines the form the customer fills in before paying. See Payment links.

Fees and who pays them

Vestrapay charges a fee per collection, and the fee depends on the channel. Initialise tells you the fee for each so you can display totals.

Field	Meaning
`amount`	What you asked to collect.
`cardFee`, `transferFee`	The fee for that channel.
`cardTotal`, `transferTotal`	What the customer pays on that channel when the customer bears the fee.
`merchantBearsCost`	When true, the customer pays exactly `amount` and the fee is deducted from what you receive.

The default comes from your payment settings in the dashboard. Pass merchantBearsCost on initialise to override it for one payment.

Customer bears the fee (default for most accounts): the customer pays the total. You settle the full amount.
You bear the fee: the customer pays the amount. You settle the amount less the fee. Verify reports this as amountSettled.

The fee is charged on the whole collection. It is never divided between split accounts.

Channels

Initialise returns the channels available for this payment: card, bank_transfer, bank_payment and ussd. Hosted checkout shows only the ones enabled for your account. Your enabled set can be narrower than the list the platform supports. If a channel you expect is missing, check your dashboard settings or contact tech@vestrapay.com.

Channel	Value	Guide
Card	`card`	Pay with card
Bank transfer	`bank_transfer`	Pay with transfer
Pay with bank	`bank_payment`	Other channels
USSD	`ussd`	Other channels

Splitting a payment

If the money from one payment should reach more than one account, add a distribution map to the initialise body. Each key is the service key of a service you have already configured, and each value is the amount to route to that service. Whatever you do not allocate goes to your primary settlement account.

{
  "amount": "1000.00",
  "email": "customer@email.com",
  "distribution": { "tuition": 600, "insurance": 150 }
}

How services, sub-accounts and splits fit together is explained in Services and splits, and the exact allocation rules are in Distribution.

After the customer pays

Receive the signed webhook and the browser callback.
Verify the reference with your secret key.
Fulfil the order once, only on success with a matching amount.

Test every path, including failure and abandonment, in the sandbox first. See Test payments.

Get started

Services & splits

Partners

Settlements

Accept payments

Choose how the customer pays

Hosted checkout

Custom checkout

Hosted checkout

Custom checkout

What initialise accepts

The callback query string

Metadata

Fees and who pays them

Channels

Splitting a payment

After the customer pays

​Choose how the customer pays

Hosted checkout

Custom checkout

​Hosted checkout

​Custom checkout

​What initialise accepts

​The callback query string

​Metadata

​Fees and who pays them

​Channels

​Splitting a payment

​After the customer pays

Choose how the customer pays

Hosted checkout

Custom checkout

What initialise accepts

The callback query string

Metadata

Fees and who pays them

Channels

Splitting a payment

After the customer pays