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

Paiements

Paiement par carte au terminal

POSThttps://api.hpay.cash/payment/

Jeton : action payment, 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.

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"
}'
Réponse
{
  "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_codeHTTPCause
3000400Montant nul ou négatif.
3001400Montant invalide (virgule au lieu du point, trop grand).
330400transaction_id invalide.
70200Carte ou PIN incorrect.
21114295 PIN erronés en 15 minutes : carte en pause 15 minutes. Le titulaire est prévenu par courriel.
701200Carte suspendue.
80400Solde du client insuffisant.
90400Compte du client inactif.
1100400Point de vente inconnu, inactif ou d'un autre compte.
409409transaction_id déjà utilisé avec d'autres données, ou remboursé.
503503Service momentanément indisponible (taux de change, comptabilité).
500500Enregistrement incertain : vérifiez avec /historiques/ avant de réessayer.

Rembourser un paiement

POSThttps://api.hpay.cash/paymentRefund/

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"
}'
Réponse
{
  "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_codeHTTPCause
30200Clé API inconnue.
40200transaction_id invalide.
50200Jeton invalide.
60200Le mode ne correspond pas à vos clés.
70200Clé secrète ou publique incorrecte.
80200Jeton expiré ou émis pour une autre action.
90400Paiement introuvable, déjà remboursé ou d'un autre mode.
409409Paiement ancien à régulariser par HPay avant remboursement.
503503Service momentanément indisponible.

Historique des paiements

POSThttps://api.hpay.cash/historiques/

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": ""
}'
Réponse
{
  "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_codeHTTPCause
30200Clé API inconnue.
330200transaction_id doit être un nombre entier sur ce filtre.
111200Aucun paiement pour ces filtres.

Suite : Points de vente →