Aller au contenu
HPay Developers
English
Guide d'intégration

Passerelle de paiement HPay

Affichez le formulaire de paiement HPay dans votre site ou votre application, sans redirection. Votre client paie avec sa carte HPay ; vous recevez une notification signée dès que le paiement est accepté.

Fonctionnement

  1. 1Votre serveur Crée une session Montant et référence de commande, envoyés à HPay avec votre clé secrète.
  2. 2Votre page Affiche le formulaire Le formulaire HPay s'affiche dans un cadre de votre page ou dans votre application.
  3. 3Votre client Paie chez HPay Carte, code PIN, puis code de confirmation reçu par courriel.
  4. 4HPay Vous notifie Notification signée envoyée à votre serveur : vous livrez la commande.
Vous ne touchez jamais aux données de carte

Le formulaire est servi par pay.hpay.cash dans un cadre isolé : ni votre code ni vos serveurs ne peuvent lire le numéro de carte ou le PIN. Vous n'avez rien à stocker ni à sécuriser de ce côté.

Avant de commencer

Il vous faut un compte Entreprise HPay avec l'API marchande activée. Vous y trouverez :

ÉlémentRôle
api_keyIdentifie votre compte.
api_public_keyClé publique, envoyée avec chaque appel.
api_secret_keyClé secrète. Elle sert aussi à vérifier la signature des notifications. À garder sur votre serveur uniquement.
marchant_idNuméro du point de vente (terminal) qui encaisse. Vous pouvez en avoir plusieurs.
modetest ou live : doit correspondre au mode de vos clés.
Déclarez vos domaines

Pour afficher le formulaire dans votre page, communiquez à HPay les adresses de vos sites (par exemple https://boutique.exemple.com). Sans domaine déclaré, le formulaire s'ouvre uniquement en page entière.

1. Créer une session de paiement

Quand votre client valide sa commande, votre serveur crée une session. Elle est valable 30 minutes et ne peut être payée qu'une fois.

POSThttps://api.hpay.cash/checkout/
Depuis votre serveur uniquement

Cet appel contient votre clé secrète : ne le faites jamais depuis un navigateur ou une application mobile.

Paramètres (JSON)

actionrequiscreate
api_key, api_secret_key, api_public_keyrequisVos clés.
moderequistest ou live
marchant_idrequisLe point de vente qui encaisse.
amountrequisstringMontant, 2 décimales au plus, dans la devise de votre compte Entreprise.
transaction_idrequisVotre référence de commande, unique : 1 à 64 caractères (lettres, chiffres, - et _).
descriptionfacultatifTexte affiché au client (255 caractères).
callback_urlfacultatifAdresse https de votre serveur qui reçoit la notification. Fortement recommandée.
return_url, cancel_urlfacultatifPages https où renvoyer le client après paiement ou annulation (page entière uniquement).
curl -X POST https://api.hpay.cash/checkout/ \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "api_key": "VOTRE_API_KEY",
    "api_secret_key": "VOTRE_SECRET_KEY",
    "api_public_key": "VOTRE_PUBLIC_KEY",
    "mode": "test",
    "marchant_id": "1001",
    "amount": "2500.00",
    "transaction_id": "CMD-20261118-0042",
    "description": "Commande n° 42",
    "callback_url": "https://boutique.exemple.com/hpay/notification"
  }'
Réponse
{
  "success": true,
  "error_code": 0,
  "message": "Session created.",
  "session_id": "cs_test_9f2c4e1ab07d4c3e8a51f0c2d6b7e913",
  "url": "https://pay.hpay.cash/?s=cs_test_9f2c4e1ab07d4c3e8a51f0c2d6b7e913",
  "amount": "2500.00",
  "currency": "HTG",
  "transaction_id": "CMD-20261118-0042",
  "expires_at": "2026-11-18 14:32:00",
  "embed_allowed_origins": ["https://boutique.exemple.com"],
  "warning": null
}

2. Afficher le formulaire

Sur un site web : intégré dans votre page

Ajoutez le script HPay et un emplacement. Transmettez à la page le session_id créé par votre serveur (jamais vos clés). Le formulaire s'ajuste tout seul en hauteur.

Les fonctions onSucces, onAnnulation et onErreur servent à mettre à jour votre page. Elles ne prouvent pas le paiement : attendez la confirmation de l'étape 3 avant de livrer.

Dans une application mobile

Chargez l'adresse url de la session dans une WebView de votre application : le client reste dans votre application, aucun navigateur externe ne s'ouvre. Renseignez return_url et cancel_url, puis interceptez la navigation vers ces adresses pour fermer la WebView.

En page entière, HPay ajoute à return_url les paramètres session_id, transaction_id et status.

<div id="hpay-paiement"></div>

<script src="https://pay.hpay.cash/sdk/hpay.js"></script>
<script>
  HPay.monter('#hpay-paiement', {
    session: 'cs_test_9f2c4e1ab07d4c3e8a51f0c2d6b7e913',
    onSucces: function (r) {
      // r.transaction_id, r.status === 'paid'
      window.location.href = '/order/merci';
    },
    onAnnulation: function () { /* retour au panier */ },
    onErreur: function (r) { console.warn(r.message); }
  });
</script>
Noms anglais disponibles

HPay.mount() équivaut à HPay.monter(), et HPay.open(session) ouvre le formulaire en page entière.

3. Confirmer le paiement sur votre serveur

La notification signée

Dès que le paiement aboutit ou échoue, HPay envoie une requête POST en JSON à votre callback_url. Répondez par un code 2xx.

Vérifiez toujours la signature avant de livrer :

  1. lisez les en-têtes X-HPay-Timestamp et X-HPay-Signature ;
  2. calculez HMAC-SHA256 de « timestamp.corps brut » avec votre api_secret_key, en hexadécimal ;
  3. comparez en temps constant, et refusez un horodatage de plus de 5 minutes ;
  4. vérifiez que transaction_id, amount et currency correspondent à votre commande.

Ou interrogez la session

À tout moment, votre serveur peut demander l'état d'une session avec action=retrieve. Utile si une notification ne vous est pas parvenue.

<?php
$body  = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_HPAY_TIMESTAMP'] ?? '';
$received  = $_SERVER['HTTP_X_HPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $ts.'.'.$body, getenv('HPAY_SECRET_KEY'));

if (!hash_equals($expected, $received) || abs(time() - (int)$ts) > 300) {
    http_response_code(400);
    exit;
}
$evt = json_decode($body, true);
if ($evt['event'] === 'payment.succeeded') {
    // Vérifier transaction_id, amount et currency, puis marquer la commande payée (une seule fois).
}
http_response_code(200);
Corps de la notification
{
  "event": "payment.succeeded",
  "session_id": "cs_test_9f2c4e1ab07d4c3e8a51f0c2d6b7e913",
  "transaction_id": "CMD-20261118-0042",
  "amount": "2500.00",
  "currency": "HTG",
  "status": "paid",
  "mode": "test",
  "paid_at": "2026-11-18 14:07:41",
  "card": "5700 **** **** 1234"
}
retrieve
POST https://api.hpay.cash/checkout/
{
  "action": "retrieve",
  "api_key": "…", "api_secret_key": "…", "api_public_key": "…",
  "mode": "test",
  "session_id": "cs_test_9f2c4e1ab07d4c3e8a51f0c2d6b7e913"
}
→ { "success": true, "status": "paid", "transaction_id": "CMD-20261118-0042", … }

Statuts d'une session

statusSignification
openCréée, le client n'a pas encore saisi sa carte.
pending_confirmationCarte et PIN acceptés, code de confirmation envoyé au client.
paidPaiement accepté : vous pouvez livrer.
failedPaiement refusé (solde insuffisant, carte bloquée…).
canceledLe client a annulé.
expiredNon payée dans le délai. Créez une nouvelle session.

Codes d'erreur

Toutes les réponses contiennent success, error_code et message. En cas d'erreur sur un champ, field indique lequel.

error_codeHTTPCause
1405Méthode autre que POST.
2400Corps JSON invalide.
3400Champ manquant ou action inconnue.
4401Clés API invalides.
5400Mode incorrect ou différent de celui de vos clés.
6400marchant_id inconnu ou désactivé.
7400Montant invalide.
8400 / 409transaction_id invalide ou déjà utilisé.
9400URL non https.
10404Session introuvable.
503503Service momentanément indisponible : réessayez.

Pendant le paiement, le client voit lui-même les refus (PIN incorrect, solde insuffisant). Après 5 PIN erronés en 15 minutes, la carte est mise en pause 15 minutes, puis repart d'elle-même.

Mode test

Avec des clés en mode test, les sessions commencent par cs_test_ et la page de paiement affiche « MODE TEST ». Demandez au support HPay une carte de test pour essayer tout le parcours, code de confirmation compris. Passez en live seulement quand la vérification de signature fonctionne.

Bonnes pratiques