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

# Checkout

> Estimate checkout, collect address, and create an invoice.

## Overview

Checkout is the bridge between a cart (items + shipping) and payment. The Commerce checkout flow is intentionally stepwise so you can validate totals before creating an invoice.

## Authentication

Requires a commerce-scoped API key: `x-commerce-api-key: ck_...`.

## Request

Endpoints:

* `POST /api/commerce/merchant/checkout/estimate`
* `POST /api/commerce/merchant/checkout/address`
* `POST /api/commerce/merchant/checkout/invoice`

## Playground (interactive reference)

* [Create a checkout invoice (commerce)](/api-spec/endpoints/commerce-checkout-invoice)

Example (create invoice):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/commerce/merchant/checkout/invoice" \
  -H "x-commerce-api-key: ck_..." \
  -H "Idempotency-Key: 123e4567-e89b-42d3-a456-556642440000" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Response

Representative invoice creation response:

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440111",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceUrl": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
    "session": "pst_...",
    "signature": "sig_...",
    "payment_session_headers": {
      "x-session-token": "pst_...",
      "x-signature": "sig_..."
    },
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "status": "unpaid"
  }
}
```

Notes:

* Commerce invoices expire after \~30 minutes (`expiresAt` in the response).
* Create a new invoice for every checkout attempt or retry; do not reuse expired or failed invoices.
* Max commerce order value is \$2500; requests above this return a checkout error.
* Offers must be deliverable within 10 days to be eligible for checkout.

## Errors

* `400` invalid checkout payload
* `401` missing/invalid commerce auth

## Examples

Recommended flow:

1. Estimate (`/estimate`) → 2) Address (`/address`) → 3) Invoice (`/invoice`)

Next: [Orders](/api-spec/commerce/orders)