Bank transfer on your screen

For apps that want their own payment screen. KetaPay gives you a one-time account number for the session; when the buyer transfers the exact amount to it, the escrow is funded. Cards aren’t available this way: card numbers must never touch your systems, so cards are only taken on KetaPay’s checkout.

Create the checkout session

As in Accept payments.

Verify the buyer

Send the buyer a one-time code and exchange it for a customer token. The payer has to be verified before money is taken.

Get the account details

const transfer = await ketapay.checkoutSessions.bankTransfer(
  session.id,
  { customerToken: token },
)

$transfer = $ketapay->checkoutSessions->bankTransfer(
    $session->id,
    ['customerToken' => $token],
);

{
  "object": "bank_transfer_instructions",
  "checkout_session_id": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "bank_name": "Zenith Bank",
  "account_number": "9912345678",
  "account_name": "KetaPay Escrow / Ada Obi",
  "amount": 45725625,
  "expires_at": "2026-10-22T12:30:00Z"
}

Calling again returns the same account while it’s valid.

Show it to the buyer

Show the bank, account number, account name and the exact amount (amount is the buyer’s total, in kobo), and when it expires. A transfer of any other amount isn’t matched.

Wait for the webhook

When the money arrives you get escrow.funded. Update your screen from your server, not from a timer. See Webhooks.

When it fails

Error	What to do
`verification_required`	The amount is above the buyer’s verification level. Send them to the session’s `url` to verify and pay there
`409` state conflict	The session is already paid, cancelled or expired. Fetch it to see which
`403` not a party	The customer token belongs to someone who isn’t the buyer on this session

In the sandbox there’s no real transfer to make: pay the session with the test helper instead.

Get started

Accept payments

Escrow

Customers

After payment

Integrate

Bank transfer on your screen

When it fails

​When it fails

When it fails