> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getopenrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout sessions

> Create hosted checkout sessions and redirect buyers to pay.getopenrails.com.

## POST /api/gateway/sessions

Creates a checkout session and returns a `checkoutUrl` to redirect the buyer to.

```bash theme={null}
curl https://dash.getopenrails.com/api/gateway/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Creator plan",
    "amount": 116,
    "customer": "buyer@example.com",
    "preferredRoute": "card",
    "redirectUrl": "https://merchant.example/success?order=ord_284",
    "metadata": {
      "order_id": "ord_284"
    }
  }'
```

### Request body

| Field               | Type   | Required | Description                                                           |
| ------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `product`           | string | Yes      | Product or plan name shown on the checkout page.                      |
| `amount`            | number | Yes      | Amount in USD. Must be greater than 0.                                |
| `customer`          | string | Yes      | Buyer email address. Used to look up or create a customer record.     |
| `preferredRoute`    | string | No       | Preferred route kind: `card`, `wallet`, or `local`.                   |
| `redirectUrl`       | string | No       | URL to redirect the buyer to after checkout completes or fails.       |
| `metadata`          | object | No       | Up to 10 key-value string pairs attached to the session.              |
| `idempotencyKey`    | string | No       | Stable key for deduplication. Recommended for order-backed checkouts. |
| `clientReferenceId` | string | No       | Your internal order or reference ID.                                  |
| `environment`       | string | No       | `sandbox` or `production`. Defaults to `sandbox`.                     |

### Response

```json theme={null}
{
  "id": "chk_demo_1779900000000",
  "object": "checkout_session",
  "checkoutUrl": "https://pay.getopenrails.com/checkout/chk_demo_1779900000000",
  "redirectUrl": "https://merchant.example/success?order=ord_284",
  "status": "routed",
  "amount": 116,
  "currency": "USD",
  "customer": "buyer@example.com",
  "metadata": {
    "order_id": "ord_284"
  }
}
```

### Fulfillment rule

Only fulfill orders after receiving a `payment.paid` webhook event. Do not fulfill on session creation or on `payment.provider_pending`. See [Webhooks](/guides/webhooks) for the full event contract.

### Status values

| Status    | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `routed`  | Session created and buyer can be redirected to `checkoutUrl`. |
| `pending` | Buyer has started checkout; payment is in progress.           |
| `paid`    | Payment confirmed. Safe to fulfill.                           |
| `failed`  | Payment failed or timed out.                                  |
| `expired` | Session expired before the buyer completed checkout.          |