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

When customers visit this URL, the hosted checkout page:

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.

GET /checkout/:payCode

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": "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.

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

Getting Started

API Endpoints

Concepts

Updates

Checkout

Checkout Flow

How Hosted Checkout Works

Internal Endpoints (Reference Only)

Path Parameters

Example Request

Response

Response Fields

Complete Checkout

Path Parameters

Request Body

Example Request

Response

Response Fields

Poll Checkout Status

Path Parameters

Example Request

Response

Possible Status Values

Checkout Flow

​Checkout Flow

​How Hosted Checkout Works

​Internal Endpoints (Reference Only)

​Path Parameters

​Example Request

​Response

​Response Fields

​Complete Checkout

​Path Parameters

​Request Body

​Example Request

​Response

​Response Fields

​Poll Checkout Status

​Path Parameters

​Example Request

​Response

​Possible Status Values

​Checkout Flow

Checkout Flow

How Hosted Checkout Works

Internal Endpoints (Reference Only)

Path Parameters

Example Request

Response

Response Fields

Complete Checkout

Path Parameters

Request Body

Example Request

Response

Response Fields

Poll Checkout Status

Path Parameters

Example Request

Response

Possible Status Values

Checkout Flow