Logo GenukaGenuka Pay
API Reference

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_SIGNATURE

Creating a session requires an API key: called from the dashboard session, it is refused with a 403.

Endpoints

  • POST /api/v1/checkout
  • GET /api/v1/checkout/{token}

Create a session

POST /api/v1/checkout
ParameterTypeRequiredDescription
amountnumberYesAmount to collect, minimum 1
currencystringYesXAF or XOF
descriptionstringNoShown to the payer (255 characters max)
payer_namestringNoPayer's name
payer_emailstringNoPayer's email
payer_phonestringNoE.164 format, e.g. +237677001122. Prefills the number on the page.
return_urlstringNoWhere to bring the payer back after payment
cancel_urlstringNoWhere to bring them back after a failure. Falls back to return_url.
expires_atISO 8601 dateNoSession expiry, in the future. Defaults to 15 minutes after creation.
metadataobjectNoYour 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" }
  }'
Response — 201
{
  "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

StatusDescription
CREATEDSession created, no payment attempt yet
INITIATED / PROCESSINGAn attempt is in flight
SUCCESSPaid. The session accepts no further payment.
FAILEDThe last attempt failed. The payer can retry until the session expires.
EXPIRED / CANCELLEDSession 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:

  • LIVE only;
  • 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