Accept payments

A buyer pays into escrow in three steps: your server creates a checkout session, the buyer pays on KetaPay’s checkout, and your server confirms the payment. KetaPay then holds the money until the seller delivers and the buyer releases it.

You need a secret key. Use your own sk_test_ key from the dashboard, or the public key from the Playground to follow along.

Choose how the buyer pays

Redirect

Send the buyer to KetaPay’s checkout. They pay by card or bank transfer and come back to your site. The quickest integration.

On your page

Open the same checkout over your page with @ketapay/checkout or @ketapay/react. The buyer never leaves your site.

Your own screen

Show a one-time account number in your own UI and let the buyer pay by transfer.

Card numbers must never touch your systems, so cards are only collected on KetaPay’s checkout.

1. Create a checkout session

Create the session on your server, when the buyer clicks pay. The price, the milestones and the parties always come from your server, never from the browser.

import KetaPay from '@ketapay/node'

const ketapay = new KetaPay(process.env.KETAPAY_SECRET_KEY!)

const session = await ketapay.checkoutSessions.create({
  amount: 45_000_000, // ₦450,000 in kobo
  category: 'goods',
  title: 'iPhone 15 Pro Max, 256GB',
  description: 'UK used, 91% battery, no scratches.',
  images: [
    { url: 'https://cdn.example.com/listings/8812/1.jpg' },
  ],
  buyer: { email: 'ada@example.com', phone: '+2348012345678' },
  seller: { email: 'tunde@example.com' },
  return_url: 'https://shop.example.com/orders/7781',
  cancel_url: 'https://shop.example.com/cart',
  external_reference: 'order_7781',
})

$session = $ketapay->checkoutSessions->create([
    'amount' => 45_000_000, // ₦450,000 in kobo
    'category' => 'goods',
    'title' => 'iPhone 15 Pro Max, 256GB',
    'description' => 'UK used, 91% battery, no scratches.',
    'images' => [
        [
            'url' =>
                'https://cdn.example.com/listings/8812/1.jpg',
        ],
    ],
    'buyer' => [
        'email' => 'ada@example.com',
        'phone' => '+2348012345678',
    ],
    'seller' => ['email' => 'tunde@example.com'],
    'return_url' => 'https://shop.example.com/orders/7781',
    'cancel_url' => 'https://shop.example.com/cart',
    'external_reference' => 'order_7781',
]);

curl https://api.ketapay.com/v1/checkout_sessions \
  -H "Authorization: Bearer $KETAPAY_SECRET_KEY" \
  -H "Idempotency-Key: order_7781" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 45000000,
    "category": "goods",
    "title": "iPhone 15 Pro Max, 256GB",
    "description": "UK used, 91% battery, no scratches.",
    "buyer": {
      "email": "ada@example.com",
      "phone": "+2348012345678"
    },
    "seller": { "email": "tunde@example.com" },
    "return_url": "https://shop.example.com/orders/7781",
    "external_reference": "order_7781"
  }'

Field	Notes
`amount`	The price in kobo. The buyer pays this plus KetaPay’s buyer fee and VAT (see Fees)
`category`	`goods`, `services`, `property`, `vehicle`, `digital` or `other`
`title`, `description`	What is being bought. Shown on the checkout and kept as the record of the deal
`buyer`, `seller`	An email or a phone each. Receipts, codes and links go there
`milestones`	Optional. Split the amount into parts released separately (see Milestones)
`release.method`	`buyer_confirms` (default) or `release_code` for in-person deals (see Release codes)
`images`, `attachments`	Photos and documents that show what was agreed
`return_url`, `cancel_url`	Where the buyer goes after paying, or if they leave
`expires_at`	15 minutes to 7 days from now; defaults to 24 hours
`external_reference`, `metadata`	Your own references (see Metadata)

The response is the session. Keep its id with your order.

{
  "id": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "object": "checkout_session",
  "livemode": false,
  "status": "open",
  "url": "https://checkout.ketapay.com/9f8e7d6c5b4a3f2e1d0c",
  "amount": 45000000,
  "currency": "NGN",
  "fees": {
    "amount": 45000000,
    "buyer_fee": 675000,
    "buyer_vat": 50625,
    "buyer_total": 45725625,
    "seller_fee": 675000,
    "commission": 0,
    "seller_payout": 44325000
  },
  "escrow_id": null,
  "external_reference": "order_7781"
}

2. Send the buyer to pay

Redirect the buyer to session.url.

app.post('/orders/:id/pay', async (req, res) => {
  const session = await createSessionFor(req.params.id)
  res.redirect(303, session.url)
})

return redirect()->away($session->url);

The buyer sees the item, the total and the payment options, and pays by card or bank transfer. When they finish, KetaPay sends them to your return_url with ?checkout_session_id=<id> added. If they leave, they go to cancel_url. To keep the buyer on your page instead, send session.url to the browser and open it there (see Checkout on your page):

KetaPay.open({ url, onSuccess: () => showThankYou() })

<KetaPayButton url={url} onSuccess={() => showThankYou()} />

Either way, confirm the payment on your server as below. Try it now in the Playground.

3. Confirm the payment

Never mark an order paid because the buyer came back to your return_url: anyone can open that URL. Confirm it one of two ways, and ideally both:

Webhook: KetaPay sends escrow.funded to your endpoint the moment the buyer pays. See Webhooks.
Fetch the session when the buyer lands on your return_url, and check its status is complete.

See Verify payments for the checks to make.

4. After payment

The session’s escrow_id is now set. The escrow follows its own lifecycle: the seller delivers, the buyer releases, and the seller is paid. See Escrow lifecycle.

Cancel an unpaid session

POST /checkout_sessions/{id}/cancel closes a session nobody has paid, for example when the order changes. A paid session can’t be cancelled; cancel the escrow instead.

Get started

Escrow

Customers

After payment

Integrate

Accept payments

Choose how the buyer pays

Redirect

On your page

Your own screen

1. Create a checkout session

2. Send the buyer to pay

3. Confirm the payment

4. After payment

Cancel an unpaid session

​Choose how the buyer pays

Redirect

On your page

Your own screen

​1. Create a checkout session

​2. Send the buyer to pay

​3. Confirm the payment

​4. After payment

​Cancel an unpaid session

Choose how the buyer pays

1. Create a checkout session

2. Send the buyer to pay

3. Confirm the payment

4. After payment

Cancel an unpaid session