Paiements
Paiement par carte au terminal
Jeton : action payment, 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.
Débite la carte HPay du client et crédite le point de vente. Le montant est exprimé dans la devise de votre compte Entreprise ; si le compte du client est dans une autre devise, HPay convertit automatiquement. Les 14 clés doivent toutes être présentes et non vides.
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
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 |
payment |
marchant_idrequisstring |
Numéro du point de vente (1 à 15 caractères). |
amountrequisnumber |
Montant avec un point décimal (5.50 et non 5,50), 2 décimales au plus. |
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 |
Votre référence unique : 1 à 64 caractères (lettres, chiffres, - et _). |
payment_linkrequisstring |
Toujours « no ». |
callback_urlrequisstring |
Non utilisé pour un paiement au terminal : envoyez « no ». |
on_success_urlrequisstring |
Non utilisé : envoyez « no ». |
on_error_urlrequisstring |
Non utilisé : envoyez « no ». |
Rejouer sans risque : si la réponse ne vous parvient pas, renvoyez exactement la même requête (même transaction_id, même montant, même carte) avec un nouveau jeton. Si le paiement avait déjà été enregistré, HPay répond success: true et already_processed: true, sans débiter une deuxième fois. En mode test, rien n'est débité mais la transaction est enregistrée.
curl -X POST https://api.hpay.cash/payment/ \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "payment",
"marchant_id": "1001",
"amount": "2500.00",
"hpay_card": "5700123456783456",
"hpay_card_pin": "••••",
"transaction_id": "TPE-20261118-0042",
"payment_link": "no",
"callback_url": "no",
"on_success_url": "no",
"on_error_url": "no"
}'{
"api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "payment",
"marchant_id": "1001",
"amount": "2500.00",
"hpay_card": "5700123456783456",
"hpay_card_pin": "••••",
"transaction_id": "TPE-20261118-0042",
"payment_link": "no",
"callback_url": "no",
"on_success_url": "no",
"on_error_url": "no"
}{
"success": true,
"already_processed": false,
"message": "Payment accepted",
"transaction_id": "TPE-20261118-0042",
"amount_paid": 2500.0,
"hpay_fees": 50.0,
"marchant_gain": 2450.0,
"marchant_master_gain": 0.0,
"devise_acheteur": "HTG",
"marchant_currency": "HTG",
"nom_acheteur": "Camille D.",
"Email_acheteur": "client@example.com",
"Email_Vendeur": "caisse@example.com",
"payment_date": "18-11-2026 14:07:41",
"transaction_mode": "test",
"token_used": "…",
"error_code": 0
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
3000 | 400 | Montant nul ou négatif. |
3001 | 400 | Montant invalide (virgule au lieu du point, trop grand). |
330 | 400 | transaction_id invalide. |
70 | 200 | Carte ou PIN incorrect. |
2111 | 429 | 5 PIN erronés en 15 minutes : carte en pause 15 minutes. Le titulaire est prévenu par courriel. |
701 | 200 | Carte suspendue. |
80 | 400 | Solde du client insuffisant. |
90 | 400 | Compte du client inactif. |
1100 | 400 | Point de vente inconnu, inactif ou d'un autre compte. |
409 | 409 | transaction_id déjà utilisé avec d'autres données, ou remboursé. |
503 | 503 | Service momentanément indisponible (taux de change, comptabilité). |
500 | 500 | Enregistrement incertain : vérifiez avec /historiques/ avant de réessayer. |
Rembourser un paiement
Jeton : action refund, valable 5 min
Annule un paiement et rend la totalité du montant au client. Le remboursement partiel n'existe pas. Attention : les codes d'erreur de ce point d'accès ne suivent pas la même numérotation que les autres.
Paramètres (JSON)
api_keyrequisstring |
Votre clé API. |
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 |
refund |
transaction_idrequisstring |
La référence du paiement à rembourser. |
curl -X POST https://api.hpay.cash/paymentRefund/ \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "refund",
"transaction_id": "TPE-20261118-0042"
}'{
"api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "refund",
"transaction_id": "TPE-20261118-0042"
}{
"success": true,
"message": "Transaction Refunded and canceled",
"transaction_id": "TPE-20261118-0042",
"refunded_details": {
"refunded_amount": "2500.00",
"refunded_date": "2026-11-18 15:02:10",
"refunded_agence": "…",
"refunded_caisse": "…",
"refunded_client": "…",
"refunded_entreprise": "…",
"refunded_hpay": "…",
"refunded_submerchant": "…"
},
"transaction_mode": "test",
"token_used": "…",
"error_code": 0
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
30 | 200 | Clé API inconnue. |
40 | 200 | transaction_id invalide. |
50 | 200 | Jeton invalide. |
60 | 200 | Le mode ne correspond pas à vos clés. |
70 | 200 | Clé secrète ou publique incorrecte. |
80 | 200 | Jeton expiré ou émis pour une autre action. |
90 | 400 | Paiement introuvable, déjà remboursé ou d'un autre mode. |
409 | 409 | Paiement ancien à régulariser par HPay avant remboursement. |
503 | 503 | Service momentanément indisponible. |
Historique des paiements
Jeton : action history, valable 15 min
Liste vos paiements, du plus récent au plus ancien. Les 9 clés doivent être envoyées ; les filtres peuvent être vides. Il n'y a pas de pagination : limitez la période.
Paramètres (JSON)
main_api_keyrequisstring |
Votre clé API (même valeur que api_key). |
tokenrequisstring |
Jeton obtenu par /token/ avec l'action indiquée. |
moderequisstring |
test ou live. |
marchant_idpeut être videstring |
Filtre : un point de vente. |
currencypeut être videstring |
Filtre : devise du client (HTG, USD…). |
transaction_idpeut être videstring |
Filtre : une référence. |
date_frompeut être videstring |
Début inclus, AAAA-MM-JJ (avec date_to). |
date_topeut être videstring |
Fin incluse, AAAA-MM-JJ. |
payment_methodepeut être videstring |
Réservé : envoyez une valeur vide. |
Aucun résultat : success vaut false et error_code "111".
curl -X POST https://api.hpay.cash/historiques/ \
-H "Content-Type: application/json" \
-d '{
"main_api_key": "YOUR_API_KEY",
"token": "FRESH_TOKEN",
"mode": "live",
"marchant_id": "",
"currency": "",
"transaction_id": "",
"date_from": "2026-11-01",
"date_to": "2026-11-18",
"payment_methode": ""
}'{
"main_api_key": "YOUR_API_KEY",
"token": "FRESH_TOKEN",
"mode": "live",
"marchant_id": "",
"currency": "",
"transaction_id": "",
"date_from": "2026-11-01",
"date_to": "2026-11-18",
"payment_methode": ""
}{
"info": {
"success": true,
"message": "Data filtered",
"transaction_mode": "live",
"error_code": "0"
},
"history": [
{
"transaction_id": "TPE-20261118-0042",
"mode": "live",
"transaction_date": "2026-11-18 14:07:41",
"client_info": {
"last": "…",
"first": "…",
"telephone": "…",
"adresse": "…",
"email": "…"
},
"sub_marchand_info": {
"id": "1001",
"name": "Caisse 1",
"phone": "…",
"mail": "…"
},
"master_marchand_info": {
"entreprise": "…",
"owner": "…",
"registered": "…"
},
"transaction_info": {
"currency_from": "HTG",
"currency_to": "HTG",
"amount": "2500.00",
"…": "…"
}
}
]
}Erreurs propres à ce point d'accès
| error_code | HTTP | Cause |
|---|---|---|
30 | 200 | Clé API inconnue. |
330 | 200 | transaction_id doit être un nombre entier sur ce filtre. |
111 | 200 | Aucun paiement pour ces filtres. |