Console
Docs/Core concepts

Payments

Create an intent, let the buyer pay, and read the verdict from the server.

#Create the payment

HTTP
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:

JSON
{
  "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.

HTTP
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:

RoutePurpose
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}/refreshask the provider again and apply the result
POST /v1/payments/{id}/cancelabandon 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.

Reference

Every route, parameter and response is generated from the OpenAPI 3.1 document.

Open the API reference