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

# Payments

> Create and manage payment sessions

# Payments API

The Payments API allows you to create, verify, and retrieve payment sessions programmatically.

## Initialize Payment

Creates a new payment session and returns a hosted checkout URL.

<Note>
  **Authentication**: Requires a **Public Key** (`cp_pk_test_` or `cp_pk_live_`)
</Note>

```http theme={null}
POST /api/v1/payments
```

### Request Body

| Parameter           | Type      | Required | Description                                                                                                                                          |
| :------------------ | :-------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`            | `number`  | Yes      | The payment amount in your account's local currency (or USD if `collectInUSD` is true)                                                               |
| `customerEmail`     | `string`  | Yes      | Customer's email address                                                                                                                             |
| `customerFirstName` | `string`  | No       | Customer's first name (2-50 characters)                                                                                                              |
| `customerLastName`  | `string`  | No       | Customer's last name (2-50 characters)                                                                                                               |
| `collectInUSD`      | `boolean` | No       | If `true`, the amount is treated as USD. Default: `false`                                                                                            |
| `reference`         | `string`  | No       | Your unique reference for this payment (8-64 alphanumeric characters). If omitted, we generate one.                                                  |
| `callbackURL`       | `string`  | No       | URL to redirect the customer after successful payment. `paymentId` (ObjectID) and `reference` (your `clientReference`) are appended as query params. |
| `failureURL`        | `string`  | No       | URL to redirect the customer on payment failure or expiration                                                                                        |
| `metadata`          | `object`  | No       | Key-value pairs of custom data (string values only)                                                                                                  |

### Example Request

```bash theme={null}
curl -X POST https://api.chainpal.org/api/v1/payments \
  -H "Authorization: Bearer cp_pk_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "customerEmail": "customer@example.com",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "reference": "ORDER12345678",
    "metadata": {
      "orderId": "12345",
      "productName": "Premium Plan"
    }
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "message": "payment initialized successfully",
  "data": {
    "paymentId": "507f1f77bcf86cd799439011",
    "paymentURL": "https://pay.chainpal.org/c/abc123xyz"
  }
}
```

### Response Fields

| Field        | Type     | Description                                       |
| :----------- | :------- | :------------------------------------------------ |
| `paymentId`  | `string` | Unique identifier for this payment session        |
| `paymentURL` | `string` | URL to redirect your customer to complete payment |

***

## Verify Payment

Retrieves the payment status and key details. Use this to verify that a payment has been completed.

<Note>
  **Authentication**: Requires a **Secret Key** (`cp_sk_test_` or `cp_sk_live_`)

  **IP Whitelisting**: This endpoint respects IP whitelist configuration.
</Note>

```http theme={null}
GET /api/v1/payments/:paymentId/verify
```

### Path Parameters

| Parameter   | Type     | Required | Description                                     |
| :---------- | :------- | :------- | :---------------------------------------------- |
| `paymentId` | `string` | Yes      | The payment ID returned from Initialize Payment |

### Example Request

```bash theme={null}
curl https://api.chainpal.org/api/v1/payments/507f1f77bcf86cd799439011/verify \
  -H "Authorization: Bearer cp_sk_test_xyz789"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "payment status fetched successfully",
  "data": {
    "paymentId": "507f1f77bcf86cd799439011",
    "paymentReference": "ORDER12345678",
    "paid": true,
    "paidAt": "2024-01-15T14:30:00Z",
    "status": "completed",
    "paymentAmount": "5000.00",
    "cryptoAmount": "3.029024",
    "paymentCurrency": "NGN",
    "token": "USDC",
    "network": "base"
  }
}
```

### Response Fields

| Field              | Type      | Description                                                                                                        |
| :----------------- | :-------- | :----------------------------------------------------------------------------------------------------------------- |
| `paymentId`        | `string`  | The payment ID                                                                                                     |
| `paymentReference` | `string`  | Your reference (as passed during payment creation, never mutated)                                                  |
| `paid`             | `boolean` | Whether the payment has been received                                                                              |
| `paidAt`           | `string`  | ISO 8601 timestamp when payment was received. Omitted from the response when the payment hasn't been received yet. |
| `status`           | `string`  | The current status of the payment (e.g., `processing`, `completed`)                                                |
| `paymentAmount`    | `string`  | The fiat amount                                                                                                    |
| `cryptoAmount`     | `string`  | The actual crypto amount collected                                                                                 |
| `paymentCurrency`  | `string`  | The fiat currency code (NGN, GHS, KES, ZAR, or USD)                                                                |
| `token`            | `string`  | The cryptocurrency used (USDT or USDC)                                                                             |
| `network`          | `string`  | The blockchain network used                                                                                        |

***

## Verify Payment by Reference

Retrieves the payment status and key details using the `clientReference` you passed during payment creation.

<Note>
  **Authentication**: Requires a **Secret Key** (`cp_sk_test_` or `cp_sk_live_`)

  **IP Whitelisting**: This endpoint respects IP whitelist configuration.
</Note>

```http theme={null}
GET /api/v1/payments/reference/:reference/verify
```

### Path Parameters

| Parameter   | Type     | Required | Description                                                |
| :---------- | :------- | :------- | :--------------------------------------------------------- |
| `reference` | `string` | Yes      | The `clientReference` you passed when creating the payment |

### Example Request

```bash theme={null}
curl https://api.chainpal.org/api/v1/payments/reference/ORDER12345678/verify \
  -H "Authorization: Bearer cp_sk_test_xyz789"
```

### Response

Same response as [Verify Payment](#verify-payment).

***

## Get Payment Details

Retrieves complete details of a payment including customer info, transaction hashes, and timestamps.

<Note>
  **Authentication**: Requires a **Secret Key** (`cp_sk_test_` or `cp_sk_live_`)

  **IP Whitelisting**: This endpoint respects IP whitelist configuration.
</Note>

```http theme={null}
GET /api/v1/payments/:paymentId
```

### Path Parameters

| Parameter   | Type     | Required | Description    |
| :---------- | :------- | :------- | :------------- |
| `paymentId` | `string` | Yes      | The payment ID |

### Example Request

```bash theme={null}
curl https://api.chainpal.org/api/v1/payments/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer cp_sk_test_xyz789"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "payment fetched successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "businessId": "507f1f77bcf86cd799439022",
    "userId": "507f1f77bcf86cd799439033",
    "environment": "test",
    "payCode": "abc123xyz",
    "fiatAmount": "5000.00",
    "collectedFiatAmount": "5000.00",
    "currency": "NGN",
    "status": "completed",
    "clientReference": "ORDER12345678",
    "paymentURL": "https://pay.chainpal.org/c/abc123xyz",
    "callbackURL": "https://yoursite.com/webhook",
    "failureURL": "https://yoursite.com/cancel",
    "customerInfo": {
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "metadata": {
      "orderId": "12345"
    },
    "cryptoAmount": "3.50",
    "collectedCryptoAmount": "3.50",
    "token": "USDC",
    "network": "base",
    "txHash": "0x123abc...",
    "primaryAddress": "0x456def...",
    "createdAt": "2024-01-15T14:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z",
    "completedAt": "2024-01-15T14:30:00Z",
    "expiresAt": "2024-01-15T15:00:00Z"
  }
}
```

### Response Fields

| Field                   | Type     | Description                                                                                                                         |
| :---------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | `string` | Unique payment identifier                                                                                                           |
| `businessId`            | `string` | Your business ID                                                                                                                    |
| `userId`                | `string` | Your user ID                                                                                                                        |
| `environment`           | `string` | `test` or `live`                                                                                                                    |
| `payCode`               | `string` | Short code used in the checkout URL                                                                                                 |
| `fiatAmount`            | `string` | Original requested fiat amount                                                                                                      |
| `collectedFiatAmount`   | `string` | Actual fiat amount collected after conversion                                                                                       |
| `currency`              | `string` | Fiat currency code                                                                                                                  |
| `status`                | `string` | Payment status (see [Types](./types))                                                                                               |
| `clientReference`       | `string` | Your reference (as passed during payment creation, never mutated). If you didn't pass one, this is auto-populated at creation time. |
| `paymentURL`            | `string` | Hosted checkout URL                                                                                                                 |
| `callbackURL`           | `string` | Webhook URL for this payment                                                                                                        |
| `failureURL`            | `string` | Failure redirect URL                                                                                                                |
| `customerInfo`          | `object` | Customer details (email, firstName, lastName)                                                                                       |
| `metadata`              | `object` | Your custom key-value data                                                                                                          |
| `cryptoAmount`          | `string` | Expected crypto amount                                                                                                              |
| `collectedCryptoAmount` | `string` | Actual crypto amount received                                                                                                       |
| `surplusAmount`         | `string` | Overpayment amount (if any)                                                                                                         |
| `deficitAmount`         | `string` | Underpayment amount (if any)                                                                                                        |
| `token`                 | `string` | Cryptocurrency token (USDT or USDC)                                                                                                 |
| `network`               | `string` | Blockchain network                                                                                                                  |
| `txHash`                | `string` | Blockchain transaction hash                                                                                                         |
| `primaryAddress`        | `string` | Deposit address used                                                                                                                |
| `totalSentAmount`       | `string` | Amount sent to exchange                                                                                                             |
| `merchantFee`           | `string` | Fee charged                                                                                                                         |
| `errorMessage`          | `string` | Error description if failed                                                                                                         |
| `createdAt`             | `string` | ISO 8601 creation timestamp                                                                                                         |
| `updatedAt`             | `string` | ISO 8601 last update timestamp                                                                                                      |
| `completedAt`           | `string` | ISO 8601 completion timestamp                                                                                                       |
| `expiresAt`             | `string` | ISO 8601 expiration timestamp                                                                                                       |

***

## List Payments

Retrieves a paginated list of your payments.

<Note>
  **Authentication**: Requires a **Secret Key** (`cp_sk_test_` or `cp_sk_live_`)

  **IP Whitelisting**: This endpoint respects IP whitelist configuration.
</Note>

```http theme={null}
GET /api/v1/payments
```

### Query Parameters

| Parameter   | Type      | Default      | Description                             |
| :---------- | :-------- | :----------- | :-------------------------------------- |
| `page`      | `integer` | `1`          | Page number                             |
| `pageSize`  | `integer` | `20`         | Number of results per page              |
| `sortBy`    | `string`  | `created_at` | Sort field (`created_at` or `status`)   |
| `sortOrder` | `string`  | `desc`       | Sort order (`asc` or `desc`)            |
| `status`    | `string`  | -            | Filter by status (see [Types](./types)) |

### Example Request

```bash theme={null}
curl "https://api.chainpal.org/api/v1/payments?page=1&pageSize=10&status=completed" \
  -H "Authorization: Bearer cp_sk_test_xyz789"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "payments fetched successfully",
  "data": {
    "data": [
      {
        "id": "507f1f77bcf86cd799439011",
        "clientReference": "ORDER12345678",
        "fiatAmount": "5000.00",
        "currency": "NGN",
        "status": "completed",
        "created_at": "2024-01-15T14:00:00Z"
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalItems": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

### Pagination Response Fields

| Field         | Type      | Description                        |
| :------------ | :-------- | :--------------------------------- |
| `data`        | `array`   | The payment records on this page   |
| `currentPage` | `integer` | The page returned (1-indexed)      |
| `pageSize`    | `integer` | Items per page                     |
| `totalItems`  | `integer` | Total payments matching the filter |
| `totalPages`  | `integer` | Total page count                   |
| `hasNext`     | `boolean` | True if a next page exists         |
| `hasPrev`     | `boolean` | True if a previous page exists     |