Checkout Sessions

A checkout session represents a single payment attempt. It holds the amount, customer information, payment method details, and status.

Session lifecycle

┌──────────┐    ┌────────┐    ┌───────────┐    ┌───────────┐
│ Created  │───▶│ Active │───▶│ Completed │    │  Expired  │
│ (init)   │    │        │    │           │    │           │
└──────────┘    └────┬───┘    └───────────┘    └───────────┘
                     │                              ▲
                     │         ┌────────┐           │
                     └────────▶│ Failed │           │
                     │         └────────┘           │
                     └──────────────────────────────┘
                              (30 min timeout)

Status transitions

Status	Description
active	Session created, waiting for payment
completed	Payment received and confirmed
failed	Payment attempt failed
expired	No payment received within 30 minutes

Creating a session

POST /v1/checkout/session/initialize

This endpoint accepts both secret keys (server-side) and public keys (inline checkout from browser). See Authentication for details.

Key parameters:

• amount (required): Amount in kobo. Minimum: 100 (NGN 1.00)
• email (required): Customer's email address
• customer_name (optional): Customer's name, displayed in the dashboard instead of "Anonymous"
• reference (optional): Your unique order reference for reconciliation
• callback_url (optional): URL to redirect to after payment (standard checkout)
• payment_methods (optional): Methods to offer, e.g. ["bank_transfer", "payid"]. May include "crypto"; ["crypto"] alone makes the checkout crypto-only
• crypto_assets (optional): Narrow the crypto assets, e.g. ["USDT:TRON"]
• metadata (optional): Custom key-value object stored with the session

Payment method priority

Payment methods are resolved in this order:

1. payment_methods parameter in the initialize request
2. API key configuration set in the dashboard
3. Default: ["bank_transfer", "payid"]

Crypto is appended automatically whenever your key has it enabled and the checkout qualifies, regardless of which list applied. Platform-disabled methods are removed unless your account is allow-listed. The response's enabled_payment_methods is the final word. Full rules: Payment Methods.

Session expiry

Sessions expire 30 minutes after creation. Expired sessions cannot accept payments.

Amount format

All amounts in the API are in kobo (minor currency units):

Display	Kobo value
NGN 1.00	100
NGN 100.00	10,000
NGN 5,000.00	500,000
NGN 1,000,000.00	100,000,000

Metadata

Store up to any custom data with the session. Metadata is returned in webhook payloads and verify responses.

{
  "metadata": {
    "order_id": "ORD-4521",
    "plan": "premium",
    "customer_id": "cust_abc123"
  }
}