Skip to content
HPay Developers
Français
Merchant API reference

HPay top-ups

Sell airtime, data bundles and gift cards to 150+ countries from your website, app or terminals.

Each top-up is paid from your USD top-up account. Fund it from your Business account (Business space › Business API › Top-up account). Without enough balance, the top-up is declined and nothing is charged.

These endpoints authenticate with your three keys, without a token: call them from your server only. In test mode purchases are simulated: nothing is charged or delivered.

Catalogue: countries, operators, products

POSThttps://api.hpay.cash/topup/

No token: your three keys in every request, from your server

Three actions to build your sales screen: countries (available countries), operators with country_id (ISO two-letter code), then products with operator_id. Each product shows your price in USD: price_usd for a fixed price, price_usd_min and price_usd_max for a free amount, chosen between min_operator and max_operator in the operator's currency.

Parameters (JSON)

api_keyrequiredstring Your API key.
api_secret_keyrequiredstring Your secret key (call from your server only).
api_public_keyrequiredstring Your public key.
moderequiredstring test or live, matching your keys.
actionrequiredstring countries | operators | products
country_idmay be emptystring For operators: ISO two-letter country code (HT, CM, SN…).
operator_idmay be emptyinteger For products: the chosen operator.
curl -X POST https://api.hpay.cash/topup/ \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "api_secret_key": "YOUR_SECRET_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "mode": "live",
  "action": "products",
  "operator_id": 1452
}'
Response
{
  "success": true,
  "message": "Products.",
  "error_code": 0,
  "operator_id": 1452,
  "products": [
    {
      "product_id": 11,
      "name": "Crédit 500 HTG",
      "product_type": "Top-up",
      "category": "Airtime",
      "price_type": "fixed",
      "currency_operator": "HTG",
      "amount_operator": 500,
      "price_usd": "3.99"
    },
    {
      "product_id": 12,
      "name": "Crédit libre",
      "product_type": "Top-up",
      "category": "Airtime",
      "price_type": "range",
      "currency_operator": "HTG",
      "min_operator": 100,
      "max_operator": 10000,
      "price_usd_min": "0.84",
      "price_usd_max": "79.80"
    }
  ]
}

Errors specific to this endpoint

error_codeHTTPCause
4401Invalid API keys.
5400Wrong mode, or different from your keys' mode.
503503Service temporarily unavailable: retry.
3400Missing country_id or operator_id.
14404No operator for this country, or unknown operator.

Quote

POSThttps://api.hpay.cash/topup/

No token: your three keys in every request, from your server

Exact price of a top-up for a number, and whether your balance covers it. Indicative: the final price is set at purchase time.

Parameters (JSON)

api_keyrequiredstring Your API key.
api_secret_keyrequiredstring Your secret key (call from your server only).
api_public_keyrequiredstring Your public key.
moderequiredstring test or live, matching your keys.
actionrequiredstring quote
operator_idrequiredinteger The operator.
product_idrequiredinteger The product.
account_idrequiredstring Number to top up, with country code (or account number, depending on the product).
amountmay be emptynumber For a free-amount product: amount in the operator's currency.
curl -X POST https://api.hpay.cash/topup/ \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "api_secret_key": "YOUR_SECRET_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "mode": "live",
  "action": "quote",
  "operator_id": 1452,
  "product_id": 12,
  "account_id": "50937000000",
  "amount": "1000"
}'
Response
{
  "success": true,
  "message": "Quote.",
  "error_code": 0,
  "operator_id": 1452,
  "product_id": 12,
  "product_name": "Crédit libre",
  "amount_operator": "1000.00",
  "currency_operator": "HTG",
  "price_usd": "7.98",
  "balance_usd": "250.00",
  "sufficient_balance": true,
  "note": "Indicative price: the final price is set when you call buy."
}

Errors specific to this endpoint

error_codeHTTPCause
4401Invalid API keys.
5400Wrong mode, or different from your keys' mode.
503503Service temporarily unavailable: retry.
7400Invalid amount, or missing for a free-amount product.
9400Unknown operator or product.
10400Amount outside the product limits.

Buy a top-up

POSThttps://api.hpay.cash/topup/

No token: your three keys in every request, from your server

Debits your top-up account, then sends the top-up. The topup.status field of the response is succeeded (delivered), pending (in progress: check with status), or refunded (declined by the operator: the amount is back in your top-up account).

Parameters (JSON)

api_keyrequiredstring Your API key.
api_secret_keyrequiredstring Your secret key (call from your server only).
api_public_keyrequiredstring Your public key.
moderequiredstring test or live, matching your keys.
actionrequiredstring buy
operator_idrequiredinteger The operator.
product_idrequiredinteger The product.
account_idrequiredstring Number to top up, with country code.
amountmay be emptynumber For a free-amount product: amount in the operator's currency.
transaction_idrequiredstring Your unique reference: 1 to 64 characters (letters, digits, - and _).

Safe retries: if the response does not reach you, resend the same transaction_id with the same data. You get the same top-up with already_processed: true, never a second one. For a gift card, give your customer delivery.pin (code, serial, instructions or link). A pending top-up settles by itself: delivered, or refunded if the operator declines it.

curl -X POST https://api.hpay.cash/topup/ \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "api_secret_key": "YOUR_SECRET_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "mode": "live",
  "action": "buy",
  "operator_id": 1452,
  "product_id": 11,
  "account_id": "50937000000",
  "amount": "",
  "transaction_id": "TOPUP-20261118-0007"
}'
Response
{
  "success": true,
  "message": "Top-up delivered.",
  "error_code": 0,
  "topup": {
    "transaction_id": "TOPUP-20261118-0007",
    "status": "succeeded",
    "mode": "live",
    "operator_id": 1452,
    "product_id": 11,
    "account_id": "50937000000",
    "amount_operator": "500.00",
    "currency_operator": "HTG",
    "price_usd": "3.99",
    "created_at": "2026-11-18 18:02:11",
    "updated_at": "2026-11-18 18:02:13",
    "delivery": {
      "operator_reference": "OP7781234",
      "amount_delivered": "500",
      "currency_delivered": "HTG",
      "account_id": "50937000000",
      "pin": {
        "code": null,
        "serial": null,
        "instructions": null,
        "redemption_url": null
      }
    },
    "balance_usd": "246.01"
  }
}

Errors specific to this endpoint

error_codeHTTPCause
4401Invalid API keys.
5400Wrong mode, or different from your keys' mode.
503503Service temporarily unavailable: retry.
6403Top-up account not opened yet, or disabled.
7400Invalid amount.
8400 / 409Invalid transaction_id, or already used for another top-up.
9400Unknown operator or product.
10400Amount outside the product limits.
11402Insufficient top-up balance (price_usd and balance_usd are returned).
12200Declined by the operator, amount refunded.
13200Being processed: check with status.

Track a top-up

POSThttps://api.hpay.cash/topup/

No token: your three keys in every request, from your server

Up-to-date status of a top-up, with the same fields as the purchase response. A pending top-up is checked with the operator on each call (at most once a minute).

Parameters (JSON)

api_keyrequiredstring Your API key.
api_secret_keyrequiredstring Your secret key (call from your server only).
api_public_keyrequiredstring Your public key.
moderequiredstring test or live, matching your keys.
actionrequiredstring status
transaction_idrequiredstring Your reference.
curl -X POST https://api.hpay.cash/topup/ \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "api_secret_key": "YOUR_SECRET_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "mode": "live",
  "action": "status",
  "transaction_id": "TOPUP-20261118-0007"
}'
Response
{
  "success": true,
  "message": "Top-up found.",
  "error_code": 0,
  "topup": {
    "transaction_id": "TOPUP-20261118-0007",
    "status": "succeeded",
    "…": "…"
  }
}

Errors specific to this endpoint

error_codeHTTPCause
4401Invalid API keys.
5400Wrong mode, or different from your keys' mode.
503503Service temporarily unavailable: retry.
14404Top-up not found (check the mode).

Balance and history

POSThttps://api.hpay.cash/topup/

No token: your three keys in every request, from your server

balance: your top-up account balance. history: your top-ups between date_from and date_to (31 days at most; last 30 days by default), 500 at most.

Parameters (JSON)

api_keyrequiredstring Your API key.
api_secret_keyrequiredstring Your secret key (call from your server only).
api_public_keyrequiredstring Your public key.
moderequiredstring test or live, matching your keys.
actionrequiredstring balance | history
date_frommay be emptystring For history: start, YYYY-MM-DD.
date_tomay be emptystring For history: end, inclusive, YYYY-MM-DD.
curl -X POST https://api.hpay.cash/topup/ \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "api_secret_key": "YOUR_SECRET_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "mode": "live",
  "action": "balance"
}'
Response
{
  "success": true,
  "message": "Balance.",
  "error_code": 0,
  "balance_usd": "246.01",
  "currency": "USD",
  "account_open": true,
  "active": true
}

Errors specific to this endpoint

error_codeHTTPCause
4401Invalid API keys.
5400Wrong mode, or different from your keys' mode.
503503Service temporarily unavailable: retry.
3400Invalid dates or range longer than 31 days.