Pay with transfer

Pay with transfer gives each payment its own one-time virtual bank account. The customer opens their banking app, sends exactly the amount shown to that account, and Vestrapay matches the inbound credit to the payment. There are no card details involved and no redirect to a bank, which makes transfer a good fallback when a card fails or an issuer is unavailable. The email address on initialise is required for this channel. If you did not send one, the request fails with payment.customer_email_required.

How it works

You initialise the payment as usual.
From checkout, you request a virtual account for that payment.
You show the bank name, account number, account name and a countdown.
The customer transfers the exact amount from their bank.
Vestrapay detects the credit, completes the payment and posts payment.completed to your webhook.
You verify and fulfil.

Hosted checkout performs steps 2 and 3 for you. The rest of this page is for custom pay screens.

Request an account

After initialise, request the account from checkout using the access code, not the secret key. There is no request body.

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/bank-transfer \
  -H "x-access-code: ACCESS_CODE"

The account details are in the data object:

{
  "status": "success",
  "data": {
    "status": "awaiting_transfer",
    "reference": "VPY_TXN_ACME001",
    "accountNumber": "0012345678",
    "bankName": "Guaranty Trust Bank",
    "accountName": "Acme Stores Limited",
    "expiresAt": "2026-09-08T10:15:00.000Z",
    "expiresInSeconds": 600
  }
}

Field	Meaning
`status`	`awaiting_transfer` while the account is open.
`accountNumber`	The virtual account the customer pays into. One-time, for this payment only.
`bankName`, `accountName`	Show both. The customer’s bank app may display the account name for confirmation.
`expiresAt`	When the account stops accepting this payment.
`expiresInSeconds`	Seconds remaining, for your countdown.

Display the bank name, account number, account name and a countdown driven by expiresInSeconds. Repeating the request while the account is still valid returns the same account, so it is safe to call again after a page refresh.

The customer must send the exact total shown on the pay screen, from their own bank account, before the countdown ends. Make the amount and the account number easy to copy, and say plainly that the amount must match.

Confirm the transfer

The customer pays at their bank, so your system learns about it asynchronously.

Subscribe to payment.completed and payment.failed on your webhook.
If your pay screen shows live progress, listen to the checkout events checkout.awaiting_transfer and then checkout.completed on GET /v1/payment/checkout/events.
Verify the reference before you fulfil.

Do not mark the order paid because the customer says they have transferred, or because their bank app shows a success screen. Only a verified success counts.

When things go wrong

Situation	What happens	What to do
Wrong amount sent	Checkout can emit `amount_mismatch` while the window is open.	Keep the same account on screen and ask the customer to send the exact total.
Account expires with no transfer	The payment does not complete and later ends as `abandoned`.	Let the customer start again with a new payment.
Customer pays after the account has expired	Do not assume the credit will be matched to this payment.	Ask the customer to contact you, and raise it with tech@vestrapay.com quoting the reference.
Account cannot be generated	`bank_transfer.failed` or `bank_transfer.virtual_account_unavailable`	Offer a retry in a moment, or offer card.
Delay at the customer’s bank	The webhook arrives later than expected.	Keep the pay screen in a waiting state, and rely on the webhook and verify rather than timing out early.

Test mode

In the sandbox, you do not need to move money. Call the simulate endpoint with the access code and choose the outcome:

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/bank-transfer/simulate \
  -H "x-access-code: ACCESS_CODE" \
  -H "Content-Type: application/json" \
  -d '{ "scenario": "success" }'

The allowed scenarios are success, failed and abandoned. The endpoint is rejected on live with HTTP 403. When the GTBank sandbox is the active transfer processor, success creates a sandbox virtual account and funds it, so the payment completes through the same webhook path as production. That makes the simulation a faithful test of your webhook handler. See Test payments.

Get started

Accept payments

Services & splits

Partners

Settlements

How it works

Request an account

Confirm the transfer

When things go wrong

Test mode

​How it works

​Request an account

​Confirm the transfer

​When things go wrong

​Test mode

How it works

Request an account

Confirm the transfer

When things go wrong

Test mode