> ## 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`.

## 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.

***

## 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.