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

Dépôts et retraits

Dépôt sur une carte

POSThttps://api.hpay.cash/deposit/

Jeton : action deposit, valable 5 min

Le client remet des espèces au point de vente, qui crédite sa carte HPay. Le point de vente est débité du montant ; le client reçoit le montant moins les frais de dépôt (1 % aujourd'hui, fixés par HPay). Une part des frais revient au point de vente.

Paramètres (JSON)

main_api_keyrequisstring Votre clé API.
public_keyrequisstring Votre clé publique (nom propre à ce point d'accès).
tokenrequisstring Jeton obtenu par /token/ avec l'action indiquée.
moderequisstring test ou live, comme vos clés.
actionrequisstring deposit
marchant_idrequisstring Numéro du point de vente (1 à 15 caractères).
amountrequisnumber Montant remis par le client.
hpay_cardrequisstring Numéro de la carte HPay (16 chiffres, commence par 57).
transaction_idrequisstring Référence unique, nombre entier.
curl -X POST https://api.hpay.cash/deposit/ \
  -H "Content-Type: application/json" \
  -d '{
  "main_api_key": "YOUR_API_KEY",
  "public_key": "YOUR_PUBLIC_KEY",
  "token": "FRESH_TOKEN",
  "mode": "test",
  "action": "deposit",
  "marchant_id": "1001",
  "amount": "1000.00",
  "hpay_card": "5700123456783456",
  "transaction_id": "2026111800042"
}'
Réponse
{
  "success": true,
  "message": "…",
  "transaction_id": "2026111800042",
  "amount_topuped": "1000.00",
  "amount_credited": 990.0,
  "hpay_fees": 10.0,
  "marchant_gain": 5.0,
  "marchant_currency": "HTG",
  "payment_date": "2026-11-18 16:00:00",
  "transaction_mode": "test",
  "token_used": "…",
  "error_code": 0
}

Erreurs propres à ce point d'accès

error_codeHTTPCause
21200Montant nul ou négatif.
330200transaction_id doit être un nombre entier.
70200Carte inconnue.
90200Compte du client suspendu.
702200Point de vente introuvable.
704200Solde du point de vente insuffisant.
705200Montant trop faible : les frais dépassent le dépôt.
7041200Pas de taux de change pour ces devises.
160200transaction_id déjà utilisé.

Retrait depuis une carte

POSThttps://api.hpay.cash/withdraw/

Jeton : action withdraw, valable 5 min

Réservé aux terminaux de paiement agréés

Ce point d'accès reçoit la carte et le code PIN du client. Il est réservé aux terminaux physiques (TPE) agréés par HPay, où le client tape lui-même son PIN. Pour un site web ou une application, utilisez la passerelle de paiement : vous n'y touchez jamais au PIN.

Le client retire des espèces au point de vente. Sa carte est débitée du montant plus les frais de retrait (2 % aujourd'hui, fixés par HPay) ; le point de vente est crédité du montant et d'une part des frais.

Paramètres (JSON)

main_api_keyrequisstring Votre clé API.
public_keyrequisstring Votre clé publique.
tokenrequisstring Jeton obtenu par /token/ avec l'action indiquée.
moderequisstring test ou live, comme vos clés.
actionrequisstring withdraw
marchant_idrequisstring Numéro du point de vente (1 à 15 caractères).
amountrequisnumber Montant remis au client, hors frais.
hpay_cardrequisstring Numéro de la carte HPay (16 chiffres, commence par 57).
hpay_card_pinrequisstring Code PIN saisi par le client sur le terminal. Ne jamais l'enregistrer.
transaction_idrequisstring Référence unique, nombre entier.

Le nom amount_topuped est conservé tel quel pour les retraits.

curl -X POST https://api.hpay.cash/withdraw/ \
  -H "Content-Type: application/json" \
  -d '{
  "main_api_key": "YOUR_API_KEY",
  "public_key": "YOUR_PUBLIC_KEY",
  "token": "FRESH_TOKEN",
  "mode": "test",
  "action": "withdraw",
  "marchant_id": "1001",
  "amount": "1000.00",
  "hpay_card": "5700123456783456",
  "hpay_card_pin": "••••",
  "transaction_id": "2026111800043"
}'
Réponse
{
  "success": true,
  "message": "…",
  "transaction_id": "2026111800043",
  "amount_topuped": "1000.00",
  "hpay_fees": 20.0,
  "marchant_gain": 10.0,
  "master_marchant_gain": 0.0,
  "marchant_currency": "HTG",
  "client_currency": "HTG",
  "payment_date": "2026-11-18 16:05:00",
  "transaction_mode": "test",
  "token_used": "…",
  "error_code": 0
}

Erreurs propres à ce point d'accès

error_codeHTTPCause
21200Montant nul ou négatif.
330200transaction_id doit être un nombre entier.
70200Carte inconnue.
701200Code PIN incorrect.
21112005 PIN erronés en 15 minutes : carte en pause 15 minutes.
90200Compte du client suspendu.
702200Point de vente introuvable.
704200Solde du client insuffisant (montant + frais).
7041200Pas de taux de change pour ces devises.
160200transaction_id déjà utilisé.

Historique des dépôts et retraits

POSThttps://api.hpay.cash/depotRetraitHistory/

Sans jeton

Lecture seule, sans jeton : la clé API et la clé publique suffisent. Les 10 clés doivent être envoyées ; les filtres peuvent être vides, mais le point de vente et le mode sont obligatoires.

Paramètres (JSON)

main_api_keyrequisstring Votre clé API.
api_public_keyrequisstring Votre clé publique.
transaction_typepeut être videstring deposit pour les dépôts, withdraw pour les retraits, vide pour les deux.
moderequisstring test ou live.
marchant_idrequisstring Le point de vente (un appel par point de vente).
client_phone_numberpeut être videstring Filtre : téléphone du client.
currencypeut être videstring Filtre : devise.
transaction_idpeut être videstring Filtre : une référence.
date_frompeut être videstring Début inclus, AAAA-MM-JJ.
date_topeut être videstring Fin incluse, AAAA-MM-JJ.
curl -X POST https://api.hpay.cash/depotRetraitHistory/ \
  -H "Content-Type: application/json" \
  -d '{
  "main_api_key": "YOUR_API_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "transaction_type": "deposit",
  "mode": "live",
  "marchant_id": "1001",
  "client_phone_number": "",
  "currency": "",
  "transaction_id": "",
  "date_from": "2026-11-01",
  "date_to": "2026-11-18"
}'
Réponse
{
  "info": {
    "success": true,
    "message": "…",
    "transaction_mode": "live",
    "error_code": 0,
    "result_count": 1
  },
  "history": [
    {
      "transaction_id": "2026111800042",
      "transaction_type": "deposit",
      "transaction_date": "2026-11-18 16:00:00",
      "transaction_data": {
        "amount_sent": "1000.00",
        "fees": "10.00",
        "total": "…",
        "currency_from": "HTG",
        "currency_to": "HTG",
        "merchant_commission": "5.00",
        "…": "…"
      }
    }
  ]
}

Erreurs propres à ce point d'accès

error_codeHTTPCause
300200Clé API ou clé publique incorrecte.
3001200Point de vente incorrect.

Suite : Cartes →