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

# Checkout

> How the hosted checkout page works

# Checkout Flow

This page documents how the hosted checkout page at `pay.chainpal.org` works. Understanding this flow helps you implement proper callback handling and user experience.

<Warning>
  **Internal API - Not Publicly Available**

  The endpoints described on this page are internal APIs that power ChainPal's hosted checkout page. They are **not part of the Developer API** and are not available for direct integration.

  To accept payments, use the [Payments API](./payments) to create a payment session and redirect customers to the returned `paymentURL`.
</Warning>

## How Hosted Checkout Works

When you create a payment using the [Payments API](./payments), you receive a `paymentURL` like:

```
https://pay.chainpal.org/c/abc123xyz456
```

When customers visit this URL, the hosted checkout page:

1. Fetches payment details and available token/network options
2. Displays your business branding and the payment amount
3. Allows the customer to select their preferred cryptocurrency and network
4. Generates a unique deposit address for the transaction
5. Shows the QR code and address for payment
6. Polls for payment confirmation
7. Redirects to your `callbackURL` on success or `failureURL` on failure

***

## Internal Endpoints (Reference Only)

Retrieves the payment configuration for a checkout session. This includes supported tokens/networks, amount limits, and business branding.

```http theme={null}
GET /checkout/:payCode
```

### Path Parameters

| Parameter | Type     | Required | Description                                         |
| :-------- | :------- | :------- | :-------------------------------------------------- |
| `payCode` | `string` | Yes      | The 12-character payment code from the checkout URL |

### Example Request

```bash theme={null}
curl https://api.chainpal.org/checkout/abc123xyz456
```

### Response

```json theme={null}
{
  "success": true,
  "message": "payment data fetched successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "customerEmail": "customer@example.com",
    "memo": "",
    "clientReference": "ORDER12345678",
    "paymentStatus": "pending",
    "paymentAmount": "5000.00",
    "paymentCurrency": "NGN",
    "supportedTokens": ["USDC", "USDT"],
    "supportedNetworksPerToken": {
      "USDC": ["base", "celo", "polygon"],
      "USDT": ["celo", "polygon"]
    },
    "businessName": "Acme Corp",
    "logoURL": "https://example.com/logo.png",
    "status": "pending",
    "callbackURL": "https://yoursite.com/return",
    "failureURL": "https://yoursite.com/cancel",
    "environment": "test",
    "minimumOutputAmount": 1000,
    "maximumOutputAmount": 1000000,
    "minimumUSDAmount": 1,
    "maximumUSDAmount": 2000,
    "createdAt": "2024-01-15T14:00:00Z",
    "updatedAt": "2024-01-15T14:00:00Z"
  }
}
```

### Response Fields

| Field                       | Type     | Description                                                         |
| :-------------------------- | :------- | :------------------------------------------------------------------ |
| `id`                        | `string` | Payment ID                                                          |
| `customerEmail`             | `string` | Customer's email                                                    |
| `clientReference`           | `string` | Your reference (or one we generated for you if you didn't pass one) |
| `paymentStatus`             | `string` | Current status                                                      |
| `paymentAmount`             | `string` | Fiat amount to be paid                                              |
| `paymentCurrency`           | `string` | Fiat currency (NGN, GHS, KES, ZAR, or USD)                          |
| `supportedTokens`           | `array`  | Available cryptocurrency tokens                                     |
| `supportedNetworksPerToken` | `object` | Map of token to available networks                                  |
| `businessName`              | `string` | Merchant's business name                                            |
| `logoURL`                   | `string` | URL to merchant's logo                                              |
| `status`                    | `string` | Payment status                                                      |
| `callbackURL`               | `string` | Success redirect URL                                                |
| `failureURL`                | `string` | Failure redirect URL                                                |
| `environment`               | `string` | `test` or `live`                                                    |
| `minimumOutputAmount`       | `number` | Minimum fiat amount allowed                                         |
| `maximumOutputAmount`       | `number` | Maximum fiat amount allowed                                         |
| `minimumUSDAmount`          | `number` | Minimum USD amount (when collecting in USD)                         |
| `maximumUSDAmount`          | `number` | Maximum USD amount (when collecting in USD)                         |

***

## Complete Checkout

Locks the payment to a specific token/network and generates a deposit address. After calling this endpoint, the customer has a limited time to complete the payment.

```http theme={null}
POST /checkout/:payCode/complete
```

### Path Parameters

| Parameter | Type     | Required | Description      |
| :-------- | :------- | :------- | :--------------- |
| `payCode` | `string` | Yes      | The payment code |

### Request Body

| Parameter | Type     | Required | Description                                |
| :-------- | :------- | :------- | :----------------------------------------- |
| `token`   | `string` | Yes      | Selected cryptocurrency (`USDT` or `USDC`) |
| `network` | `string` | Yes      | Selected blockchain network                |

### Example Request

```bash theme={null}
curl -X POST https://api.chainpal.org/checkout/abc123xyz456/complete \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "network": "base"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "message": "api payment processing",
  "data": {
    "receiveAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "validUntil": "2024-01-15T15:00:00Z",
    "totalPayableAmount": "3.029024"
  }
}
```

### Response Fields

| Field                | Type     | Description                                            |
| :------------------- | :------- | :----------------------------------------------------- |
| `receiveAddress`     | `string` | The deposit address for the customer to send crypto to |
| `validUntil`         | `string` | ISO 8601 timestamp when this address expires           |
| `totalPayableAmount` | `string` | The exact crypto amount the customer must send         |

<Warning>
  The customer must send the **exact** `totalPayableAmount` to the
  `receiveAddress` before `validUntil`. Underpayments or late payments may not
  be processed automatically.
</Warning>

***

## Poll Checkout Status

Retrieves the current status of a checkout session. Use this for polling to detect when payment is received.

```http theme={null}
GET /checkout/:payCode/status
```

### Path Parameters

| Parameter | Type     | Required | Description      |
| :-------- | :------- | :------- | :--------------- |
| `payCode` | `string` | Yes      | The payment code |

### Example Request

```bash theme={null}
curl https://api.chainpal.org/checkout/abc123xyz456/status
```

### Response

```json theme={null}
{
  "success": true,
  "message": "api payment status fetched successfully",
  "data": "pending"
}
```

### Possible Status Values

| Status       | Description                                  |
| :----------- | :------------------------------------------- |
| `pending`    | Waiting for customer to select token/network |
| `processing` | Payment received, being processed            |
| `completed`  | Payment successful and settled               |
| `expired`    | Payment window expired                       |
| `failed`     | Payment failed                               |

***

## Checkout Flow

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout Page
    participant ChainPal API

    Customer->>Checkout Page: Visit paymentURL
    Checkout Page->>ChainPal API: GET /checkout/:payCode
    ChainPal API-->>Checkout Page: Payment config & supported tokens

    Customer->>Checkout Page: Select token & network
    Checkout Page->>ChainPal API: POST /checkout/:payCode/complete
    ChainPal API-->>Checkout Page: Deposit address & amount

    Checkout Page->>Customer: Display QR code & address

    loop Poll for status
        Checkout Page->>ChainPal API: GET /checkout/:payCode/status
        ChainPal API-->>Checkout Page: Current status
    end

    Customer->>Blockchain: Send crypto payment
    ChainPal API-->>Checkout Page: Status: completed
    Checkout Page->>Customer: Show success message
```