Recharges HPay
Vendez du crédit téléphonique, des forfaits internet et des cartes cadeaux vers plus de 150 pays, depuis votre site, votre application ou vos terminaux.
Chaque recharge est payée depuis votre compte de recharge en USD. Alimentez-le depuis votre compte Entreprise (espace Entreprise › API Entreprise › Compte de recharge). Sans solde suffisant, la recharge est refusée et rien n'est débité.
Ces points d'accès s'authentifient avec vos trois clés, sans jeton : appelez-les uniquement depuis votre serveur. En mode test, les achats sont simulés : rien n'est débité ni livré.
Catalogue : pays, opérateurs, produits
Sans jeton : vos trois clés dans chaque requête, depuis votre serveur
Trois actions pour construire votre écran de vente : countries (pays disponibles), operators avec country_id (code ISO à 2 lettres), puis products avec operator_id. Chaque produit indique son prix pour vous, en USD : price_usd pour un prix fixe, price_usd_min et price_usd_max pour un montant libre, choisi entre min_operator et max_operator dans la devise de l'opérateur.
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
api_secret_keyrequisstring |
Votre clé secrète (appel depuis votre serveur uniquement). |
api_public_keyrequisstring |
Votre clé publique. |
moderequisstring |
test ou live, comme vos clés. |
actionrequisstring |
countries | operators | products |
country_idpeut être videstring |
Pour operators : code pays ISO à 2 lettres (HT, CM, SN…). |
operator_idpeut être videinteger |
Pour products : l'opérateur choisi. |
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"
}
]
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Clés API invalides. |
5 | 400 | Mode incorrect ou différent de celui de vos clés. |
503 | 503 | Service momentanément indisponible : réessayez. |
3 | 400 | country_id ou operator_id manquant. |
14 | 404 | Aucun opérateur pour ce pays, ou opérateur inconnu. |
Devis
Sans jeton : vos trois clés dans chaque requête, depuis votre serveur
Prix exact d'une recharge pour un numéro, et si votre solde suffit. Indicatif : le prix définitif est fixé au moment de l'achat.
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
api_secret_keyrequisstring |
Votre clé secrète (appel depuis votre serveur uniquement). |
api_public_keyrequisstring |
Votre clé publique. |
moderequisstring |
test ou live, comme vos clés. |
actionrequisstring |
quote |
operator_idrequisinteger |
L'opérateur. |
product_idrequisinteger |
Le produit. |
account_idrequisstring |
Numéro à recharger, avec l'indicatif du pays (ou numéro de compte selon le produit). |
amountpeut être videnumber |
Pour un produit à montant libre : montant dans la devise de l'opérateur. |
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."
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Clés API invalides. |
5 | 400 | Mode incorrect ou différent de celui de vos clés. |
503 | 503 | Service momentanément indisponible : réessayez. |
7 | 400 | Montant invalide, ou manquant pour un produit à montant libre. |
9 | 400 | Opérateur ou produit inconnu. |
10 | 400 | Montant hors des limites du produit. |
Acheter une recharge
Sans jeton : vos trois clés dans chaque requête, depuis votre serveur
Débite votre compte de recharge, puis envoie la recharge. Le champ topup.status de la réponse vaut succeeded (livrée), pending (en cours : vérifiez avec status), ou refunded (refusée par l'opérateur : le montant est revenu sur votre compte de recharge).
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
api_secret_keyrequisstring |
Votre clé secrète (appel depuis votre serveur uniquement). |
api_public_keyrequisstring |
Votre clé publique. |
moderequisstring |
test ou live, comme vos clés. |
actionrequisstring |
buy |
operator_idrequisinteger |
L'opérateur. |
product_idrequisinteger |
Le produit. |
account_idrequisstring |
Numéro à recharger, avec l'indicatif du pays. |
amountpeut être videnumber |
Pour un produit à montant libre : montant dans la devise de l'opérateur. |
transaction_idrequisstring |
Votre référence unique : 1 à 64 caractères (lettres, chiffres, - et _). |
Rejouer sans risque : si la réponse ne vous parvient pas, renvoyez le même transaction_id avec les mêmes données. Vous recevez la même recharge avec already_processed: true, jamais une seconde. Pour une carte cadeau, remettez à votre client delivery.pin (code, numéro de série, instructions ou lien). Une recharge pending se règle seule : livrée, ou remboursée si l'opérateur la refuse.
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"
}
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Clés API invalides. |
5 | 400 | Mode incorrect ou différent de celui de vos clés. |
503 | 503 | Service momentanément indisponible : réessayez. |
6 | 403 | Compte de recharge pas encore ouvert, ou désactivé. |
7 | 400 | Montant invalide. |
8 | 400 / 409 | transaction_id invalide, ou déjà utilisé pour une autre recharge. |
9 | 400 | Opérateur ou produit inconnu. |
10 | 400 | Montant hors des limites du produit. |
11 | 402 | Solde du compte de recharge insuffisant (price_usd et balance_usd sont renvoyés). |
12 | 200 | Refusée par l'opérateur, montant remboursé. |
13 | 200 | En cours de traitement : vérifiez avec status. |
Suivre une recharge
Sans jeton : vos trois clés dans chaque requête, depuis votre serveur
État à jour d'une recharge, avec les mêmes champs que la réponse d'achat. Une recharge pending est vérifiée auprès de l'opérateur à chaque appel (au plus une fois par minute).
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
api_secret_keyrequisstring |
Votre clé secrète (appel depuis votre serveur uniquement). |
api_public_keyrequisstring |
Votre clé publique. |
moderequisstring |
test ou live, comme vos clés. |
actionrequisstring |
status |
transaction_idrequisstring |
Votre référence. |
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",
"…": "…"
}
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Clés API invalides. |
5 | 400 | Mode incorrect ou différent de celui de vos clés. |
503 | 503 | Service momentanément indisponible : réessayez. |
14 | 404 | Recharge introuvable (vérifiez le mode). |
Solde et historique
Sans jeton : vos trois clés dans chaque requête, depuis votre serveur
balance : solde de votre compte de recharge. history : vos recharges entre date_from et date_to (31 jours au plus ; par défaut les 30 derniers jours), 500 au plus.
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
api_secret_keyrequisstring |
Votre clé secrète (appel depuis votre serveur uniquement). |
api_public_keyrequisstring |
Votre clé publique. |
moderequisstring |
test ou live, comme vos clés. |
actionrequisstring |
balance | history |
date_frompeut être videstring |
Pour history : début, AAAA-MM-JJ. |
date_topeut être videstring |
Pour history : fin incluse, AAAA-MM-JJ. |
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
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
4 | 401 | Clés API invalides. |
5 | 400 | Mode incorrect ou différent de celui de vos clés. |
503 | 503 | Service momentanément indisponible : réessayez. |
3 | 400 | Dates invalides ou période de plus de 31 jours. |