> ## 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 for a commerce order.

## Overview

Checkout is a 3-step flow:

1. estimate totals → 2) collect/validate shipping address → 3) create an invoice.

## Authentication

Merchant checkout routes require `x-commerce-api-key`.

## Request

### Estimate checkout

```ts theme={null}
const estimate = await pepay.commerce.checkout.estimate({
  customer_id: 'cust_123456',
  items: [
    {
      productId: 'B08N5WRWNW',
      retailer: 'amazon',
      title: 'Item',
      quantity: 1,
      price: 9.99
    }
  ]
});
```

### Submit address

```ts theme={null}
const address = await pepay.commerce.checkout.address({
  customer_id: 'cust_123456',
  estimateId: '550e8400-e29b-41d4-a716-446655440000',
  address: {
    first_name: 'Jane',
    last_name: 'Doe',
    street_address: '123 Main St',
    address_line2: 'Apt 4B',
    city: 'Miami',
    state: 'FL',
    zip_code: '33101',
    country: 'US',
    phone: '+13055550123',
    email: 'jane@example.com'
  }
});
```

### Create invoice

```ts theme={null}
const invoice = await pepay.commerce.checkout.createInvoice({
  customer_id: 'cust_123456',
  estimateId: '550e8400-e29b-41d4-a716-446655440000',
  addressId: '550e8400-e29b-41d4-a716-446655440222',
  refundDestinationWalletAddressBsc: '0x0000000000000000000000000000000000000001'
});
```

## Response

Example invoice response (truncated):

```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": "550e8400-e29b-41d4-a716-446655440444",
    "signature": "<signatureHash>.<timestamp>",
    "payment_session_headers": {
      "x-session-token": "550e8400-e29b-41d4-a716-446655440444",
      "x-signature": "<signatureHash>.<timestamp>"
    },
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "customerId": "cust_123456",
    "amount": 13.99,
    "status": "unpaid",
    "expiresAt": 1765844400,
    "endpoints": {
      "checkOrder": "/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440111",
      "checkPayment": "/api/commerce/merchant/payments/550e8400-e29b-41d4-a716-446655440111/status",
      "cancelOrder": "/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440111/cancel"
    }
  }
}
```

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.

## Errors

* `400` invalid checkout/address payload
* `401` missing/invalid commerce API key
* `409` idempotency conflict on invoice creation

## Examples

* Treat invoice creation as a write: always pass an `Idempotency-Key` when calling the API directly.
  Next: [Orders](/sdk/commerce/orders)