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.
Authentication: Requires a Public Key (cp_pk_test_ or cp_pk_live_)
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 (12-16 alphanumeric characters). If omitted, we generate one. |
callbackURL | string | No | URL to redirect the customer after successful payment. Payment ID and reference 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
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": "[email protected]",
"customerFirstName": "John",
"customerLastName": "Doe",
"reference": "ORDER12345678",
"metadata": {
"orderId": "12345",
"productName": "Premium Plan"
}
}'
Response
{
"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.
Authentication: Requires a Secret Key (cp_sk_test_ or cp_sk_live_)IP Whitelisting: This endpoint respects IP whitelist configuration.
GET /api/v1/payments/:paymentId/verify
Path Parameters
| Parameter | Type | Required | Description |
|---|
paymentId | string | Yes | The payment ID returned from Initialize Payment |
Example Request
curl https://api.chainpal.org/api/v1/payments/507f1f77bcf86cd799439011/verify \
-H "Authorization: Bearer cp_sk_test_xyz789"
Response
{
"success": true,
"message": "payment status fetched successfully",
"data": {
"paymentId": "507f1f77bcf86cd799439011",
"paymentReference": "checkoutORDER12345678",
"paid": true,
"paidAt": "2024-01-15T14:30:00Z",
"paymentAmount": "5000.00",
"paymentCurrency": "NGN",
"token": "USDC",
"network": "base"
}
}
Response Fields
| Field | Type | Description |
|---|
paymentId | string | The payment ID |
paymentReference | string | Your reference (prefixed with checkout) |
paid | boolean | Whether the payment has been received |
paidAt | string | ISO 8601 timestamp when payment was received (empty if not paid) |
paymentAmount | string | The fiat amount |
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 |
Get Payment Details
Retrieves complete details of a payment including customer info, transaction hashes, and timestamps.
Authentication: Requires a Secret Key (cp_sk_test_ or cp_sk_live_)IP Whitelisting: This endpoint respects IP whitelist configuration.
GET /api/v1/payments/:paymentId
Path Parameters
| Parameter | Type | Required | Description |
|---|
paymentId | string | Yes | The payment ID |
Example Request
curl https://api.chainpal.org/api/v1/payments/507f1f77bcf86cd799439011 \
-H "Authorization: Bearer cp_sk_test_xyz789"
Response
{
"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",
"reference": "checkoutORDER12345678",
"paymentURL": "https://pay.chainpal.org/c/abc123xyz",
"callbackURL": "https://yoursite.com/webhook",
"customerInfo": {
"email": "[email protected]",
"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) |
reference | string | Your reference (prefixed with checkout) |
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.
Authentication: Requires a Secret Key (cp_sk_test_ or cp_sk_live_)IP Whitelisting: This endpoint respects IP whitelist configuration.
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) |
Example Request
curl "https://api.chainpal.org/api/v1/payments?page=1&pageSize=10&status=completed" \
-H "Authorization: Bearer cp_sk_test_xyz789"
Response
{
"success": true,
"message": "payments fetched successfully",
"data": {
"items": [
{
"_id": "507f1f77bcf86cd799439011",
"reference": "checkoutORDER12345678",
"fiatAmount": "5000.00",
"currency": "NGN",
"status": "completed",
"created_at": "2024-01-15T14:00:00Z"
}
],
"page": 1,
"pageSize": 10,
"totalItems": 1,
"totalPages": 1
}
}
