Dépôts et retraits
Dépôt sur une carte
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"
}'{
"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"
}{
"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_code | HTTP | Cause |
|---|---|---|
21 | 200 | Montant nul ou négatif. |
330 | 200 | transaction_id doit être un nombre entier. |
70 | 200 | Carte inconnue. |
90 | 200 | Compte du client suspendu. |
702 | 200 | Point de vente introuvable. |
704 | 200 | Solde du point de vente insuffisant. |
705 | 200 | Montant trop faible : les frais dépassent le dépôt. |
7041 | 200 | Pas de taux de change pour ces devises. |
160 | 200 | transaction_id déjà utilisé. |
Retrait depuis une carte
Jeton : action withdraw, valable 5 min
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"
}'{
"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"
}{
"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_code | HTTP | Cause |
|---|---|---|
21 | 200 | Montant nul ou négatif. |
330 | 200 | transaction_id doit être un nombre entier. |
70 | 200 | Carte inconnue. |
701 | 200 | Code PIN incorrect. |
2111 | 200 | 5 PIN erronés en 15 minutes : carte en pause 15 minutes. |
90 | 200 | Compte du client suspendu. |
702 | 200 | Point de vente introuvable. |
704 | 200 | Solde du client insuffisant (montant + frais). |
7041 | 200 | Pas de taux de change pour ces devises. |
160 | 200 | transaction_id déjà utilisé. |
Historique des dépôts et retraits
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"
}'{
"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"
}{
"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_code | HTTP | Cause |
|---|---|---|
300 | 200 | Clé API ou clé publique incorrecte. |
3001 | 200 | Point de vente incorrect. |