{
"checkout_id": "chk_1M2N3o4P5q6R7s8T",
"status": "completed",
"amount": "50.00",
"currency": "USD",
"customer": {
"id": "cust_1a2b3c4d5e6f",
"email": "jane@example.com",
"name": "Jane Doe"
},
"created_at": "2026-01-24T14:30:00.000Z",
"updated_at": "2026-01-24T14:35:00.000Z",
"recurring": {
"interval": "month",
"interval_count": 1
},
"payment_status": "requires_payment_method",
"source_type": "CHECKOUT_SESSION",
"reference": "order_9876",
"charge": {
"payment_id": "pay_1a2b3c4d5e",
"status": "succeeded",
"amount": "10.00",
"currency": "USD",
"created_at": "2026-04-27T12:00:00Z",
"updated_at": "2026-04-27T12:00:05Z",
"reference": "order_9876",
"billing_reason": "purchase",
"checkout_id": "chk_8T9u0V1w2X3y4Z5a",
"is_refundable": true,
"amount_paid": "10.00",
"amount_remaining": "0.00",
"fee_usd": "0.59",
"fees": {
"amount": "8.73",
"currency": "USD"
},
"merchant_bears_cost": true,
"platform_fee": null,
"destination_amount": null,
"fee_paid_by": "merchant",
"payment_method": "NGN_BANK_TRANSFER",
"channel": "checkout",
"narration": "Pro plan",
"meta": {
"order_id": "ORD-9876"
},
"message": "Successful",
"customer": {
"name": "<string>",
"email": "<string>"
},
"line_items": [
{
"product_id": "prod_abc123",
"product_name": "Premium Plan",
"quantity": 1,
"unit_amount": "50.00",
"currency": "USD",
"line_total": "50.00"
}
],
"subscription_id": null,
"invoice": {
"invoice_id": "inv_9a8b7c6d5e",
"number": "inv_9a8b7c6d5e",
"subscription_id": "sub_1a2b3c4d5e",
"period_start": "2026-04-01T00:00:00Z",
"period_end": "2026-05-01T00:00:00Z",
"kind": "cycle"
},
"refunds": [
"ref_1a2b3c4d5e"
],
"status_history": [
{
"status": "succeeded",
"occurred_at": "2026-01-24T14:35:00.000Z",
"reason": "<string>"
}
],
"payment_method_details": {
"type": "bank_transfer",
"bank_transfer": {
"sender_name": "JANE ADEYEMI",
"sender_bank": "Guaranty Trust Bank",
"sender_account_number": "2294879124",
"session_id": "000013260922104115000821734502",
"virtual_account": {
"id": "va_8Hs2kQ4mZpXv",
"account_number": "9902847361",
"bank_name": "Example Bank",
"type": "permanent",
"expires_at": null
}
}
},
"completed_at": "2026-04-27T12:00:05Z"
},
"payment_method": "NGN_BANK_TRANSFER",
"customer_details": {
"email": "jane@example.com",
"name": "Jane Doe"
},
"success_url": "https://yourapp.com/success",
"cancel_url": "https://yourapp.com/cancel",
"products": [
{
"product_id": "prod_abc123",
"product_name": "Premium Plan",
"quantity": 1,
"unit_amount": "50.00",
"currency": "USD",
"price_type": "fixed",
"line_total": "50.00",
"minimum_amount": "10.00",
"maximum_amount": "500.00"
}
],
"billing_currency": "NGN",
"platform_fee": "20000.00",
"destination_amount": "80000.00",
"session_mode": "CART",
"metadata": {
"order_id": "ORD-9876"
},
"expires_at": "2026-01-24T15:30:00.000Z",
"completed_at": "2026-01-24T14:35:00.000Z"
}The checkout session object
A checkout session ties one or more products to a customer, provided at creation or collected on the hosted page, and produces a hosted checkout URL. It tracks the customer through payment and, once paid, links to the payment it created.
customer vs customer_details
Two fields carry the buyer, and they answer different questions.
customeris the customer record behind this checkout:{ id, email, name }. It is non-null exactly when a record exists.customer_detailsis what the buyer supplied:{ email, name }. It is present whenever an identity was collected, record or no record.
checkout.completed webhook.
| State | customer | customer_details |
|---|---|---|
| No identity collected yet | null | null |
| Customer passed at creation | cust_ record | {email, name} |
Guest identified on the hosted page, customer_creation: if_required (default) | null | {email, name} |
Guest identified on the hosted page, customer_creation: always | cust_ record | {email, name} |
| Payment link with a fixed price | null | {email, name} |
customer_details when you want the buyer’s email and name and do not care whether a record backs them. Read customer when you need an id you can pass back to the customers API.
See Whether a guest becomes a customer for how customer_creation decides which row you land on.
customer_details is additive. customer behaves exactly as it always did, so anything that reads customer keeps working. What is new is that a checkout with no customer record behind it used to send no identity at all on completion, and now carries one.Checkout session details returned by GET /v1/checkout-sessions/{checkout_id}.
Unique checkout identifier.
"chk_1M2N3o4P5q6R7s8T"
Current lifecycle status of the checkout session. open: awaiting customer payment, where every new session starts. completed: payment succeeded, a terminal state. expired: the session window elapsed before payment, a terminal state. cancelled: cancelled before completion, a terminal state.
open, completed, expired, cancelled "completed"
Total amount in currency.
"50.00"
Base currency code.
"USD"
The customer attached to the checkout.
Show child attributes
Show child attributes
ISO 8601 creation timestamp.
"2026-01-24T14:30:00.000Z"
ISO 8601 last-updated timestamp.
"2026-01-24T14:35:00.000Z"
Present only for a subscription checkout; null for a one-time checkout.
Show child attributes
Show child attributes
Payment lifecycle for the checkout. requires_payment_method, requires_confirmation, requires_action, processing, succeeded, failed, or canceled.
requires_payment_method, requires_confirmation, requires_action, processing, succeeded, failed, canceled "requires_payment_method"
What created the checkout, e.g. CHECKOUT_SESSION or API.
"CHECKOUT_SESSION"
The reference you set when you created the session. null if you set none.
"order_9876"
The payment created by this checkout, once payment has been attempted. null before then.
Show child attributes
Show child attributes
The payment method selected for the checkout, if any. For every method except card, this is the exact corridor collected, such as NGN_BANK_TRANSFER, MOMO_GHS, or CRYPTO. Card charges report CARD rather than USD_CARD or NGN_CARD; read the currency to tell which card corridor collected it.
"NGN_BANK_TRANSFER"
What the buyer supplied; present whenever an identity was collected, record or no record. null before then.
Show child attributes
Show child attributes
URL the customer is redirected to after successful payment.
"https://yourapp.com/success"
URL the customer is redirected to if they cancel.
"https://yourapp.com/cancel"
Resolved product line items. Populated for CART sessions; may be null for SELECTION sessions before the customer picks a product.
Show child attributes
Show child attributes
Currency the customer selected for billing.
"NGN"
The platform's cut of this sale, in the base currency of the sale. The key is always present; it reads null, not "0.00", on a checkout that carries no fee, and on a checkout that split the sale with transfer_data.amount instead. See Platform fees.
"20000.00"
The seller's contracted share of this sale, in the base currency of the sale. Null on a checkout that carries no split, and on one that split the sale with platform_fee instead.
"80000.00"
How products are presented. CART sums a fixed set of items; SELECTION lets the customer pick one from a group.
CART, SELECTION "CART"
Public metadata you attached at session creation.
{ "order_id": "ORD-9876" }
ISO 8601 expiry timestamp.
"2026-01-24T15:30:00.000Z"
ISO 8601 timestamp when the session was completed.
"2026-01-24T14:35:00.000Z"