Product · Global Airtime & Data

International Top-Up

Send mobile airtime and data bundles to hundreds of destinations worldwide with real-time foreign exchange conversion and carrier routing.

Base paths/api/v1/partner/intl-airtime · /api/v1/partner/intl-data

Authx-api-key (+ x-signature on purchases)

Rate limit30 requests / 60s per namespace

Webhooksinternational.airtime.success · international.data.success

Part 1 — International Airtime

List supported countries

GET /partner/intl-airtime/countries

API key only

List airtime providers for country

GET /partner/intl-airtime/providers

API key only

Query Param	Type	Required	Description
countryCode	string	required	2-letter ISO country code (e.g. `GH`, `KE`, `GB`, `US`)

cURL

curl "https://api.billpadi.com/api/v1/partner/intl-airtime/providers?countryCode=GH" \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Providers retrieved",
  "data": [
    { "operatorId": "mtn-gh", "name": "MTN Ghana", "countryCode": "GH" },
    { "operatorId": "vodafone-gh", "name": "Telecel Ghana", "countryCode": "GH" }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/intl-airtime/providers"
}

List airtime products / variations

GET /partner/intl-airtime/products

API key only

Query Param	Type	Required	Description
providerId	string	required	Operator ID from providers list (e.g. `mtn-gh`)
productTypeId	integer	required	Product type identifier (e.g. `1` for top-up)

Purchase international airtime

POST /partner/intl-airtime/purchase

Signature required

Field	Type	Required	Description
phone	string	required	Full international MSISDN including country code (e.g. `233201234567`)
amount	number	required	Amount to send
countryCode	string	required	2-letter ISO country code (e.g. `GH`)
operatorId	string	required	Carrier operator ID (e.g. `mtn-gh`)
productCode	string	required	Product code from products catalog
countryName	string	optional	Country name
variationCode	string	optional	Denomination/variation code if applicable
partnerReference	string	required	Unique reference string (2–100 characters) for idempotency

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/intl-airtime/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "phone": "233201234567",
    "amount": 20,
    "countryCode": "GH",
    "countryName": "Ghana",
    "operatorId": "mtn-gh",
    "productCode": "mtn-gh-airtime",
    "partnerReference": "PR-IA-91234"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "International airtime purchase successful",
  "data": {
    "transactionReference": "TXN_1720603200000_9C0D",
    "partnerReference": "PR-IA-91234",
    "status": "success",
    "countryCode": "GH",
    "amount": 20
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/intl-airtime/purchase"
}

Get international airtime status

GET /partner/intl-airtime/transactions/:reference

API key only

Part 2 — International Data

List supported data countries

GET /partner/intl-data/countries

API key only

List data providers for country

GET /partner/intl-data/providers

API key only

Query Param	Type	Required	Description
countryCode	string	required	2-letter ISO country code

List international data packages

GET /partner/intl-data/products

API key only

Query Param	Type	Required	Description
operator	string	required	Operator slug/ID (e.g. `mtn-gh`)

cURL

curl "https://api.billpadi.com/api/v1/partner/intl-data/products?operator=mtn-gh" \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Products retrieved",
  "data": [
    {
      "productCode": "mtn-gh-1gb",
      "name": "MTN Ghana 1GB Data",
      "amount": 15,
      "validity": "30 Days"
    }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/intl-data/products"
}

Purchase international data bundle

POST /partner/intl-data/purchase

Signature required

Field	Type	Required	Description
phone	string	required	Recipient international phone number
productCode	string	required	Data bundle code
operatorId	string	required	Carrier operator ID
countryCode	string	required	2-letter ISO country code
countryName	string	required	Country name
amount	number	required	Package amount
partnerReference	string	required	Unique reference string for idempotency

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/intl-data/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "phone": "233201234567",
    "productCode": "mtn-gh-1gb",
    "operatorId": "mtn-gh",
    "countryCode": "GH",
    "countryName": "Ghana",
    "amount": 15,
    "partnerReference": "PR-ID-40218"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "International data purchase successful",
  "data": {
    "transactionReference": "TXN_1720603200000_0D1E",
    "partnerReference": "PR-ID-40218",
    "status": "success",
    "countryCode": "GH"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/intl-data/purchase"
}

Get international data status

GET /partner/intl-data/transactions/:reference

API key only

← PreviousCrypto Trading