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.
Internal API - Not Publicly AvailableThe 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 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, you receive a paymentURL like:
https://pay.chainpal.org/c/abc123xyz456
- Fetches payment details and available token/network options
- Displays your business branding and the payment amount
- Allows the customer to select their preferred cryptocurrency and network
- Generates a unique deposit address for the transaction
- Shows the QR code and address for payment
- Polls for payment confirmation
- 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.
Path Parameters
| Parameter | Type | Required | Description |
|---|
payCode | string | Yes | The 12-character payment code from the checkout URL |
Example Request
curl https://api.chainpal.org/checkout/abc123xyz456
Response
{
"success": true,
"message": "payment data fetched successfully",
"data": {
"id": "507f1f77bcf86cd799439011",
"customerEmail": "[email protected]",
"memo": "",
"paymentReference": "checkoutORDER12345",
"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",
"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 |
paymentReference | string | Payment reference |
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 |
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.
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
curl -X POST https://api.chainpal.org/checkout/abc123xyz456/complete \
-H "Content-Type: application/json" \
-d '{
"token": "USDC",
"network": "base"
}'
Response
{
"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 |
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.
GET /checkout/:payCode/status
Path Parameters
| Parameter | Type | Required | Description |
|---|
payCode | string | Yes | The payment code |
Example Request
curl https://api.chainpal.org/checkout/abc123xyz456/status
Response
{
"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
