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
- 1Votre serveur Crée une session Montant et référence de commande, envoyés à HPay avec votre clé secrète.
- 2Votre page Affiche le formulaire Le formulaire HPay s'affiche dans un cadre de votre page ou dans votre application.
- 3Votre client Paie chez HPay Carte, code PIN, puis code de confirmation reçu par courriel.
- 4HPay Vous notifie Notification signée envoyée à votre serveur : vous livrez la commande.
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ément | Rôle |
|---|---|
api_key | Identifie votre compte. |
api_public_key | Clé publique, envoyée avec chaque appel. |
api_secret_key | Clé secrète. Elle sert aussi à vérifier la signature des notifications. À garder sur votre serveur uniquement. |
marchant_id | Numéro du point de vente (terminal) qui encaisse. Vous pouvez en avoir plusieurs. |
mode | test ou live : doit correspondre au mode de vos clés. |
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.
Cet appel contient votre clé secrète : ne le faites jamais depuis un navigateur ou une application mobile.
Paramètres (JSON)
actionrequis | create |
api_key, api_secret_key, api_public_keyrequis | Vos clés. |
moderequis | test ou live |
marchant_idrequis | Le point de vente qui encaisse. |
amountrequisstring | Montant, 2 décimales au plus, dans la devise de votre compte Entreprise. |
transaction_idrequis | Votre référence de commande, unique : 1 à 64 caractères (lettres, chiffres, - et _). |
descriptionfacultatif | Texte affiché au client (255 caractères). |
callback_urlfacultatif | Adresse https de votre serveur qui reçoit la notification. Fortement recommandée. |
return_url, cancel_urlfacultatif | Pages 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"
}'<?php
$body = json_encode([
'action' => 'create',
'api_key' => getenv('HPAY_API_KEY'),
'api_secret_key' => getenv('HPAY_SECRET_KEY'),
'api_public_key' => getenv('HPAY_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',
]);
$c = curl_init('https://api.hpay.cash/checkout/');
curl_setopt_array($c, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
]);
$session = json_decode(curl_exec($c), true);
// $session['session_id'] → cs_test_…const r = await fetch('https://api.hpay.cash/checkout/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
action: 'create',
api_key: process.env.HPAY_API_KEY,
api_secret_key: process.env.HPAY_SECRET_KEY,
api_public_key: process.env.HPAY_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',
}),
});
const session = await r.json(); // session.session_id → cs_test_…{
"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>webView.settings.javaScriptEnabled = true
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(v: WebView, req: WebResourceRequest): Boolean {
val u = req.url.toString()
if (u.startsWith(RETURN_URL)) { verifyOnServer(); finish(); return true }
if (u.startsWith(CANCEL_URL)) { finish(); return true }
return false
}
}
webView.loadUrl(session.url)func webView(_ w: WKWebView, decidePolicyFor a: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
let u = a.request.url?.absoluteString ?? ""
if u.hasPrefix(returnURL) { verifyOnServer(); dismiss(animated: true) }
if u.hasPrefix(cancelURL) { dismiss(animated: true) }
decisionHandler(u.hasPrefix(returnURL) || u.hasPrefix(cancelURL) ? .cancel : .allow)
}
webView.load(URLRequest(url: URL(string: session.url)!))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 :
- lisez les en-têtes X-HPay-Timestamp et X-HPay-Signature ;
- calculez HMAC-SHA256 de « timestamp.corps brut » avec votre api_secret_key, en hexadécimal ;
- comparez en temps constant, et refusez un horodatage de plus de 5 minutes ;
- 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);import crypto from 'node:crypto';
import express from 'express';
app.post('/hpay/notification', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-HPay-Timestamp') || '';
const received = req.get('X-HPay-Signature') || '';
const expected = crypto.createHmac('sha256', process.env.HPAY_SECRET_KEY)
.update(ts + '.' + req.body).digest('hex');
const ok = received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
const evt = JSON.parse(req.body);
if (evt.event === 'payment.succeeded') { /* marquer la commande payée */ }
res.sendStatus(200);
});{
"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"
}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
| status | Signification |
|---|---|
open | Créée, le client n'a pas encore saisi sa carte. |
pending_confirmation | Carte et PIN acceptés, code de confirmation envoyé au client. |
paid | Paiement accepté : vous pouvez livrer. |
failed | Paiement refusé (solde insuffisant, carte bloquée…). |
canceled | Le client a annulé. |
expired | Non 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_code | HTTP | Cause |
|---|---|---|
1 | 405 | Méthode autre que POST. |
2 | 400 | Corps JSON invalide. |
3 | 400 | Champ manquant ou action inconnue. |
4 | 401 | Clés API invalides. |
5 | 400 | Mode incorrect ou différent de celui de vos clés. |
6 | 400 | marchant_id inconnu ou désactivé. |
7 | 400 | Montant invalide. |
8 | 400 / 409 | transaction_id invalide ou déjà utilisé. |
9 | 400 | URL non https. |
10 | 404 | Session introuvable. |
503 | 503 | Service 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
- Gardez api_secret_key sur votre serveur, dans une variable d'environnement. Jamais dans une page, une application ou un dépôt de code.
- Ne demandez jamais la carte ou le PIN dans vos propres formulaires : seul le formulaire HPay doit les recevoir.
- Livrez sur la notification signée ou sur action=retrieve, pas sur onSucces ni sur return_url seuls.
- Traitez chaque notification une seule fois : la même peut arriver deux fois.
- Utilisez un transaction_id unique par commande : HPay refuse les doublons, ce qui évite de faire payer deux fois.