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

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

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

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

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

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


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