Bills / API reference

Purchase a product

Buy airtime, data, electricity, TV, or education products from the catalogue.

POST/products/buy

Authentication

Send your live API key in the Authorization: Bearer header. All requests use https://api.celerlinks.com/api-service.

This is a live financial request. Send a unique X-Idempotency-Key for each purchase and reuse it only for retries of that exact request. Online payment returns HTTP 202 with data.payment_link; initialization is not confirmation of delivery.

Request parameters

product_codestring · body · required

Use the code from the current product catalogue.

recipient_numberstring · body · required

Phone number, meter number, or smartcard number for the selected product.

scenariostring · body · optional

Sandbox only: success (default), failure, or pending. Rejected on live routes.

amountnumber · body · optional

Amount in NGN for variable-value products such as airtime and electricity.

payment_methodstring · body · optional

wallet or online. Wallet purchases debit your Celerlinks balance.

pinstring · body · optional

Your four-digit transaction PIN, required for wallet payments when a PIN is set.

access_tokenstring · body · optional

Recipient-validation token, if returned by the provider.

Request identity

Use the X-Idempotency-Key header. Successful responses and validation errors are retained for 24 hours. Use a new key for a new purchase or corrected payload. A request still in progress returns 409.

Errors and retry guidance

Examples are illustrative. Catalogue IDs, product codes, prices, and provider-specific fields must come from your current API responses.

cURL request

curl --request POST 'https://api.celerlinks.com/api-service/products/buy' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'X-Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "product_code": "PRODUCT_CODE",
  "recipient_number": "RECIPIENT_NUMBER",
  "amount": 1000,
  "payment_method": "wallet",
  "pin": "YOUR_PIN"
}'

Illustrative response

{
  "success": true,
  "message": "Request completed successfully",
  "data": {
    "id": 123,
    "reference": "TRANSACTION_REFERENCE",
    "status": "processing",
    "amount": 1000
  }
}