#Create the payment
POST /v1/payments
authorization: DPoP <token>
dpop: <proof>
idempotency-key: order-9f2c-01
content-type: application/json
{
"reference": "order-9f2c",
"amount": 250000,
"currency": "KES",
"recipient_id": "rcp_...", // optional: who gets paid
"metadata": { "order_id": "9f2c" }, // optional, returned to you
"return_url": "https://your.app/thanks"
}
Response 201:
{
"id": "pay_...",
"status": "requires_action",
"amount_minor": 250000,
"currency": "KES",
"reference": "order-9f2c",
"checkout_url": "https://api.paygate.nxtgi.com/c/..."
}
reference is your order id and is unique per app. Sending the same reference again returns the same payment, never a second charge.
#Let the buyer pay
Send the buyer to checkout_url, or complete the payment in your own UI.
Optional: start the attempt yourself.
POST /v1/payments/{id}/confirm
{ "method": "mobile_money", "phone": "254712345678" }
method is mobile_money or card. For mobile money, phone receives the prompt. For card, omit phone and open the returned redirect_url.
Other payment routes:
| Route | Purpose |
|---|---|
GET /v1/payments/{id} | current status and attempts |
GET /v1/payments?reference=... | find one by your reference |
GET /v1/payments?status=&limit= | list (scoped to your environment) |
POST /v1/payments/{id}/refresh | ask the provider again and apply the result |
POST /v1/payments/{id}/cancel | abandon an unpaid intent; never reverses a settled payment |
#Know when it is paid
Read GET /v1/payments/{id} until status is terminal, or wait for the payment.succeeded webhook. Terminal states: succeeded, failed, cancelled, expired.
Show success only when the server says succeeded. Do not trust a query string, a deep link or a browser return URL.