API Reference · Payments
Checkout Sessions
Hosted checkout sessions (checkout.rafiqpay.net/c/{id}). The customer pays by card, by bank transfer to a one-time account, or from their rafiqPay wallet, and your balance is credited when the payment is confirmed.
The checkout.session object
Represents a checkout.session entity in the rafiqPay system.
| Field | Type & Flags | Description |
|---|---|---|
| id | string | Unique identifier (cs_live_... or cs_test_...). |
| amount | string | Order subtotal as decimal Naira string ("35000.00"). |
| status | enum | open | complete | expired. A session expires when it is not paid in time. |
| chargeStatus | enum | pending | succeeded | failed | abandoned. Fulfil the order only when this is succeeded. |
| url | string | Hosted checkout redirect URL. |
Example checkout.session JSON
checkout.session example payload
{
"id": "cs_test_kanzu_99182736",
"object": "checkout.session",
"amount": "35000.00",
"currency": "NGN",
"status": "open",
"chargeStatus": "pending",
"url": "https://checkout.rafiqpay.net/c/cs_test_kanzu_99182736"
}Endpoints & Operations
POST/v1/checkout/sessionsIn plan 035
Create a checkout session
Creates a new Hosted Checkout session for a one-time payment.
Request Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| amount | string | Required | Decimal Naira amount string matching ^\d+(\.\d{1,2})?$. |
| currency | string | Optional | Only "NGN". Defaults to NGN. |
| customerEmail | string | Required | The customer’s email. |
| successUrl | string | Optional | HTTPS address to send the customer to after paying. {CHECKOUT_SESSION_ID} is replaced with the session id. |
| cancelUrl | string | Optional | HTTPS address to send the customer to if they leave. |
| saveCard | boolean | Optional | Show a "Save this card" box. The card is saved for your business only if the customer ticks it and pays by card. See Saved cards. |
Request Example
POST /v1/checkout/sessions
cURL · v1
curl -X POST "https://api.rafiqpay.net/v1/checkout/sessions" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
-H "Idempotency-Key: idem_create-checkout-session_01" \
-H "Content-Type: application/json" \
-d '{
"amount": "35000.00",
"currency": "NGN",
"customerEmail": "amina@kanzu.ng",
"successUrl": "https://kanzu.ng/success",
"cancelUrl": "https://kanzu.ng/cancel",
"saveCard": true
}'Response (200 OK)
Response payload
{
"id": "cs_test_kanzu_99182736",
"object": "checkout.session",
"amount": "35000.00",
"currency": "NGN",
"status": "open",
"url": "https://checkout.rafiqpay.net/c/cs_test_kanzu_99182736"
}GET/v1/checkout/sessions/:idIn plan 035
Retrieve a checkout session
Retrieves the current state of a Checkout Session, with chargeStatus, and once paid the paymentMethod and fee.
Request Example
GET /v1/checkout/sessions/:id
cURL · v1
curl -X GET "https://api.rafiqpay.net/v1/checkout/sessions/:id" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"Response (200 OK)
Response payload
{
"id": "cs_test_kanzu_99182736",
"object": "checkout.session",
"status": "complete",
"amount": "35000.00",
"chargeStatus": "succeeded",
"paymentMethod": "bank_transfer",
"fee": "525.00"
}GET/v1/checkout/sessionsProposed
List checkout sessions
Returns a cursor-paginated list of Checkout Sessions.
Request Example
GET /v1/checkout/sessions
cURL · v1
curl -X GET "https://api.rafiqpay.net/v1/checkout/sessions" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"Response (200 OK)
Response payload
{
"object": "list",
"data": [
{
"id": "cs_test_kanzu_99182736",
"amount": "35000.00"
}
],
"hasMore": false,
"nextCursor": null
}POST/v1/checkout/sessions/:id/cancelProposed
Cancel a checkout session
Expires an open Checkout Session immediately.
Request Example
POST /v1/checkout/sessions/:id/cancel
cURL · v1
curl -X POST "https://api.rafiqpay.net/v1/checkout/sessions/:id/cancel" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
-H "Idempotency-Key: idem_cancel-checkout-session_01"Response (200 OK)
Response payload
{
"id": "cs_test_kanzu_99182736",
"status": "cancelled"
}Related Webhook Events
These events are dispatched to your webhook endpoints when actions occur on this resource: