Verify payments - KetaPay Docs

A buyer landing on your return_url is not proof of payment: the URL can be opened by anyone. Before you ship, unlock or mark an order paid, confirm the payment with KetaPay.

Fetch the session

When the buyer comes back, read checkout_session_id from the URL and fetch the session from your server.

const session = await ketapay.checkoutSessions.retrieve(
  req.query.checkout_session_id,
)

const paid =
  session.status === 'complete' &&
  session.external_reference === order.reference &&
  session.amount === order.amountKobo

if (paid) await markOrderPaid(order, session.escrow_id)

$session = $ketapay->checkoutSessions->retrieve(
    $_GET['checkout_session_id'],
);

$paid =
    $session->status === 'complete' &&
    $session->external_reference === $order->reference &&
    $session->amount === $order->amount_kobo;

if ($paid) {
    markOrderPaid($order, $session->escrow_id);
}

curl https://api.ketapay.com/v1/checkout_sessions/$SESSION_ID \
  -H "Authorization: Bearer $KETAPAY_SECRET_KEY"

What to check

Check	Why
`status` is `complete`	`open` means not paid yet; `expired` or `cancelled` will never be paid
`external_reference` matches your order	The session id in the URL could belong to another order
`amount` matches what you charged	Guards against a session made for a different price
`escrow_id` is set	The escrow that now holds the money; store it with the order
`livemode` is what you expect	A test payment must never fulfil a live order

Use the webhook too

escrow.funded reaches your server even if the buyer closes the tab before coming back. Handle both paths and make fulfilment idempotent: whichever arrives first marks the order paid, the second does nothing. See Webhooks.

Session statuses

Status	Meaning
`open`	Waiting for payment
`complete`	Paid. `escrow_id` is set
`expired`	Not paid by `expires_at`. You get `checkout_session.expired`
`cancelled`	You cancelled it