# 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

```bash
POST /v1/checkout/session/initialize
```

This endpoint accepts both secret keys (server-side) and public keys (inline checkout from browser). See [Authentication](/guide/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.

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