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

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

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

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

Authentication: Requires a Secret Key (cp_sk_test_ or cp_sk_live_)IP Whitelisting: This endpoint respects IP whitelist configuration.

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

curl https://api.chainpal.org/api/v1/payments/reference/ORDER12345678/verify \
  -H "Authorization: Bearer cp_sk_test_xyz789"

Response

Same response as Verify Payment.

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",
    "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)
`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.

Authentication: Requires a Secret Key (cp_sk_test_ or cp_sk_live_)IP Whitelisting: This endpoint respects IP whitelist configuration.

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)

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

​Payments API

​Initialize Payment

​Request Body

​Example Request

​Response

​Response Fields

​Verify Payment

​Path Parameters

​Example Request

​Response

​Response Fields

​Verify Payment by Reference

​Path Parameters

​Example Request

​Response

​Get Payment Details

​Path Parameters

​Example Request

​Response

​Response Fields

​List Payments

​Query Parameters

​Example Request

​Response

​Pagination Response Fields

Payments API

Initialize Payment

Request Body

Example Request

Response

Response Fields

Verify Payment

Path Parameters

Example Request

Response

Response Fields

Verify Payment by Reference

Path Parameters

Example Request

Response

Get Payment Details

Path Parameters

Example Request

Response

Response Fields

List Payments

Query Parameters

Example Request

Response

Pagination Response Fields