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
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
}'{
"api_key": "YOUR_API_KEY",
"api_secret_key": "YOUR_SECRET_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"mode": "live",
"action": "products",
"operator_id": 1452
}{
"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_code | HTTP | Cause |
|---|---|---|
4 | 401 | Invalid API keys. |
5 | 400 | Wrong mode, or different from your keys' mode. |
503 | 503 | Service temporarily unavailable: retry. |
3 | 400 | Missing country_id or operator_id. |
14 | 404 | No operator for this country, or unknown operator. |
Quote
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"
}'{
"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"
}{
"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_code | HTTP | Cause |
|---|---|---|
4 | 401 | Invalid API keys. |
5 | 400 | Wrong mode, or different from your keys' mode. |
503 | 503 | Service temporarily unavailable: retry. |
7 | 400 | Invalid amount, or missing for a free-amount product. |
9 | 400 | Unknown operator or product. |
10 | 400 | Amount outside the product limits. |
Buy a top-up
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"
}'{
"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"
}{
"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_code | HTTP | Cause |
|---|---|---|
4 | 401 | Invalid API keys. |
5 | 400 | Wrong mode, or different from your keys' mode. |
503 | 503 | Service temporarily unavailable: retry. |
6 | 403 | Top-up account not opened yet, or disabled. |
7 | 400 | Invalid amount. |
8 | 400 / 409 | Invalid transaction_id, or already used for another top-up. |
9 | 400 | Unknown operator or product. |
10 | 400 | Amount outside the product limits. |
11 | 402 | Insufficient top-up balance (price_usd and balance_usd are returned). |
12 | 200 | Declined by the operator, amount refunded. |
13 | 200 | Being processed: check with status. |
Track a top-up
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"
}'{
"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"
}{
"success": true,
"message": "Top-up found.",
"error_code": 0,
"topup": {
"transaction_id": "TOPUP-20261118-0007",
"status": "succeeded",
"…": "…"
}
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Invalid API keys. |
5 | 400 | Wrong mode, or different from your keys' mode. |
503 | 503 | Service temporarily unavailable: retry. |
14 | 404 | Top-up not found (check the mode). |
Balance and history
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"
}'{
"api_key": "YOUR_API_KEY",
"api_secret_key": "YOUR_SECRET_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"mode": "live",
"action": "balance"
}{
"success": true,
"message": "Balance.",
"error_code": 0,
"balance_usd": "246.01",
"currency": "USD",
"account_open": true,
"active": true
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Invalid API keys. |
5 | 400 | Wrong mode, or different from your keys' mode. |
503 | 503 | Service temporarily unavailable: retry. |
3 | 400 | Invalid dates or range longer than 31 days. |