Aller au contenu
HPay Developers
English
Référence de l'API marchande

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

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

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
}'
Réponse
{
  "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_codeHTTPCause
4401Clés API invalides.
5400Mode incorrect ou différent de celui de vos clés.
503503Service momentanément indisponible : réessayez.
3400country_id ou operator_id manquant.
14404Aucun opérateur pour ce pays, ou opérateur inconnu.

Devis

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

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"
}'
Réponse
{
  "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_codeHTTPCause
4401Clés API invalides.
5400Mode incorrect ou différent de celui de vos clés.
503503Service momentanément indisponible : réessayez.
7400Montant invalide, ou manquant pour un produit à montant libre.
9400Opérateur ou produit inconnu.
10400Montant hors des limites du produit.

Acheter une recharge

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

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"
}'
Réponse
{
  "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_codeHTTPCause
4401Clés API invalides.
5400Mode incorrect ou différent de celui de vos clés.
503503Service momentanément indisponible : réessayez.
6403Compte de recharge pas encore ouvert, ou désactivé.
7400Montant invalide.
8400 / 409transaction_id invalide, ou déjà utilisé pour une autre recharge.
9400Opérateur ou produit inconnu.
10400Montant hors des limites du produit.
11402Solde du compte de recharge insuffisant (price_usd et balance_usd sont renvoyés).
12200Refusée par l'opérateur, montant remboursé.
13200En cours de traitement : vérifiez avec status.

Suivre une recharge

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

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"
}'
Réponse
{
  "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_codeHTTPCause
4401Clés API invalides.
5400Mode incorrect ou différent de celui de vos clés.
503503Service momentanément indisponible : réessayez.
14404Recharge introuvable (vérifiez le mode).

Solde et historique

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

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"
}'
Réponse
{
  "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_codeHTTPCause
4401Clés API invalides.
5400Mode incorrect ou différent de celui de vos clés.
503503Service momentanément indisponible : réessayez.
3400Dates invalides ou période de plus de 31 jours.