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) — Array of enabled methods: ["bank_transfer", "payid"]
• 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"]

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"
  }
}