Hosted Checkout
Create a Genuka Pay payment page, redirect your customer to it and track the outcome.
Hosted checkout collects payments without you building a form: you create a session, redirect the customer to the URL returned, and the Genuka Pay page handles the operator choice, the phone number, the confirmation and the receipt. To compare with the direct API, see Choosing your integration.
Required headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURECreating a session requires an API key: called from the dashboard session, it is refused with a 403.
Endpoints
POST /api/v1/checkoutGET /api/v1/checkout/{token}
Create a session
POST /api/v1/checkout| Parameter | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount to collect, minimum 1 |
currency | string | Yes | XAF or XOF |
description | string | No | Shown to the payer (255 characters max) |
payer_name | string | No | Payer's name |
payer_email | string | No | Payer's email |
payer_phone | string | No | E.164 format, e.g. +237677001122. Prefills the number on the page. |
return_url | string | No | Where to bring the payer back after payment |
cancel_url | string | No | Where to bring them back after a failure. Falls back to return_url. |
expires_at | ISO 8601 date | No | Session expiry, in the future. Defaults to 15 minutes after creation. |
metadata | object | No | Your own references. Sent back in the webhooks of this session's payments. |
curl -X POST "https://api-pay.genuka.com/api/v1/checkout" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"currency": "XOF",
"description": "Order #10001",
"return_url": "https://shop.example.com/thanks",
"cancel_url": "https://shop.example.com/cart",
"expires_at": "2026-09-19T12:00:00Z",
"metadata": { "order_id": "10001" }
}'{
"data": {
"id": "01k7c4t9m2y8x5b3n6q0r1s2t3",
"token": "01k7c4t9m5a7b8c9d0e1f2g3h4",
"company_id": "01k5...",
"application_id": "01k5...",
"amount": 10000,
"currency": "XOF",
"description": "Order #10001",
"status": "CREATED",
"status_label": "Created",
"payer": { "name": null, "email": null, "phone": null },
"urls": {
"checkout": "https://api-pay.genuka.com/checkout/01k7c4t9m5a7b8c9d0e1f2g3h4",
"return": "https://shop.example.com/thanks",
"cancel": "https://shop.example.com/cart"
},
"expires_at": "2026-09-19T12:00:00.000000Z",
"metadata": { "order_id": "10001" },
"created_at": "2026-09-19T11:45:00.000000Z",
"updated_at": "2026-09-19T11:45:00.000000Z"
}
}Redirect the customer to urls.checkout. The token identifies the session: it is what you pass to GET /api/v1/checkout/{token}.
There is no idempotency key on this endpoint: each call creates a new session. Keep the mapping between your order and the token on your side.
Retrieve a session
GET /api/v1/checkout/{token}Same shape as above, plus payins: the session's payment attempts, in the payments format (track_id, status, failure, fees…).
Statuses
| Status | Description |
|---|---|
CREATED | Session created, no payment attempt yet |
INITIATED / PROCESSING | An attempt is in flight |
SUCCESS | Paid. The session accepts no further payment. |
FAILED | The last attempt failed. The payer can retry until the session expires. |
EXPIRED / CANCELLED | Session closed |
The status follows the latest attempt. A session whose expires_at has passed accepts no payment — the page shows an expiry screen (HTTP 410) — even if its status has not changed yet: rely on expires_at.
What the payer sees
The urls.checkout page:
- shows your name, logo, the amount and the
description; - lets the payer pick their country and operator, then enter their number (prefilled with
payer_phone); - offers card payment when it is enabled on your account (a dashboard setting);
- shows the fees added to the amount when the customer bears them (
fee_bearer = CUSTOMER); - tracks the payment live and lets the payer retry after a failure.
In sandbox, the page works with the test numbers.
Payer return
Once the payment finishes, the payer is sent to return_url (or cancel_url on failure) with status, reference (the track_id) and token (the session's) appended to the URL. Details in Payments API.
Do not rely on the browser return
The customer may close the tab before reaching return_url, and URL parameters can be edited. A payment is only confirmed by the transaction.success webhook or by GET /api/v1/checkout/{token}.
Webhooks
Payments made on the page fire the same transaction.* events as an API payment. Their data.metadata carries the session's metadata: that is where your order reference belongs.
Receipt
Once the payment succeeds, the page offers the payer a PDF receipt:
GET https://api-pay.genuka.com/checkout/{token}/receipt?track_id={track_id}This URL is public (no signature required) but only answers with the track_id of a successful payment of that session; otherwise 404.
WhatsApp receipt
If you turn on the WhatsApp receipt option in your company settings, the payer also gets their receipt on WhatsApp after a successful payment. Conditions:
LIVEonly;- only for payments made through a hosted checkout or a collection link, not through
POST /api/v1/payments; - only when the payer's number is in international format (a card payment has none).
How is this guide?
Last updated on