v1

latestOpenAPI 3.0.32026-07-264469137.7 KB

Checkout Sessions

Retrieve a checkout session

Retrieve the details of a checkout session by its ID, including resolved product line items and charge information.

The charge field is null while the session is OPEN and populated once the customer submits a payment.

Requires payments:read scope.

get/v1/checkout-sessions/{checkout_id}

Path parameters

checkout_idstring required

The checkout ID returned when the session was created.

Response

Checkout session retrieved successfully.

checkout_idstring required

Unique checkout identifier.

status'OPEN' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' required

Current lifecycle status of the checkout session. OPEN: Awaiting customer payment. New sessions start here. COMPLETED: Payment succeeded. This is a terminal state. EXPIRED: The session window elapsed before payment. This is a terminal state. CANCELLED: Canceled before completion. This is a terminal state.

Payment lifecycle for the checkout. requires_payment_method, requires_confirmation, requires_action, processing, succeeded, failed, or canceled.

source_typestring nullable

What created the checkout, e.g. CHECKOUT_SESSION or API.

amountstring required

Total amount in currency.

currencystring required

Base currency code.

referencestring nullable

Merchant-supplied or auto-generated reference.

payment_methodstring nullable

The payment method selected for the checkout, if any.

success_urlstring uri nullable

URL the customer is redirected to after successful payment.

cancel_urlstring uri nullable

URL the customer is redirected to if they cancel.

billing_currencystring nullable

Currency the customer selected for billing.

session_mode'CART' | 'SELECTION' nullable

How products are presented. CART sums a fixed set of items; SELECTION lets the customer pick one from a group.

metadataobject nullable

Public metadata you attached at session creation.

created_atstring date-time required

ISO 8601 creation timestamp.

expires_atstring date-time nullable

ISO 8601 expiry timestamp.

completed_atstring date-time nullable

ISO 8601 timestamp when the session was completed.

updated_atstring date-time required

ISO 8601 last-updated timestamp.

Example response

{
  "checkout_id": "chk_1a2b3c4d5e6f",
  "status": "COMPLETED",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "payment_status": "requires_payment_method",
  "source_type": "CHECKOUT_SESSION",
  "amount": "50.00",
  "currency": "USD",
  "reference": "order_9876",
  "charge": {
    "reference": "order_9876",
    "payment_id": "pay_1a2b3c4d5e",
    "billing_reason": "purchase",
    "checkout_id": "chk_6f7g8h9i0j",
    "status": "succeeded",
    "is_refundable": true,
    "amount": "10.00",
    "amount_paid": "10.00",
    "amount_remaining": "0.00",
    "currency": "USD",
    "fee_usd": "0.59",
    "merchant_bears_cost": true,
    "payment_method": "card",
    "channel": "checkout",
    "narration": "Pro plan",
    "meta": {
      "order_id": "ORD-9876"
    },
    "message": "Successful",
    "line_items": [
      {
        "product_id": "prod_abc123",
        "product_name": "Premium Plan",
        "quantity": 1,
        "unit_amount": "50.00",
        "currency": "USD",
        "line_total": "50.00"
      }
    ],
    "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",
        "provider_reference": "TXN_ABC123"
      }
    ],
    "created_at": "2026-04-27T12:00:00Z",
    "updated_at": "2026-04-27T12:00:05Z",
    "completed_at": "2026-04-27T12:00:05Z"
  },
  "payment_method": "card",
  "customer": {
    "id": "cust_1a2b3c4d5e6f",
    "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",
      "minimum_amount": "10.00",
      "maximum_amount": "500.00",
      "line_total": "50.00"
    }
  ],
  "billing_currency": "NGN",
  "session_mode": "CART",
  "metadata": {
    "order_id": "ORD-9876"
  },
  "created_at": "2026-01-24T14:30:00.000Z",
  "expires_at": "2026-01-24T15:30:00.000Z",
  "completed_at": "2026-01-24T14:35:00.000Z",
  "updated_at": "2026-01-24T14:35:00.000Z"
}