HPay payment gateway
Show the HPay payment form inside your website or app, with no redirect. Your customer pays with their HPay card; you receive a signed notification as soon as the payment is accepted.
How it works
- 1Your server Creates a session Amount and order reference, sent to HPay with your secret key.
- 2Your page Shows the form The HPay form appears in a frame on your page or inside your app.
- 3Your customer Pays on HPay Card, PIN, then a confirmation code received by email.
- 4HPay Notifies you Signed notification sent to your server: you fulfil the order.
The form is served by pay.hpay.cash in an isolated frame: neither your code nor your servers can read the card number or PIN. There is nothing for you to store or secure on that side.
Before you start
You need an HPay Business account with the merchant API enabled. It gives you:
| Item | Purpose |
|---|---|
api_key | Identifies your account. |
api_public_key | Public key, sent with every call. |
api_secret_key | Secret key. It is also used to verify notification signatures. Keep it on your server only. |
marchant_id | Number of the point of sale (terminal) receiving the money. You can have several. |
mode | test or live: must match the mode of your keys. |
To show the form inside your page, send HPay the addresses of your websites (for example https://shop.example.com). Without a declared domain, the form only opens as a full page.
1. Create a payment session
When your customer places an order, your server creates a session. It is valid for 30 minutes and can be paid only once.
This call contains your secret key: never make it from a browser or a mobile app.
Parameters (JSON)
actionrequired | create |
api_key, api_secret_key, api_public_keyrequired | Your keys. |
moderequired | test or live |
marchant_idrequired | The point of sale receiving the money. |
amountrequiredstring | Amount, at most 2 decimals, in your Business account currency. |
transaction_idrequired | Your unique order reference: 1 to 64 characters (letters, digits, - and _). |
descriptionoptional | Text shown to the customer (255 characters). |
callback_urloptional | https address on your server that receives the notification. Strongly recommended. |
return_url, cancel_urloptional | https pages to send the customer to after payment or cancellation (full page only). |
curl -X POST https://api.hpay.cash/checkout/ \
-H "Content-Type: application/json" \
-d '{
"action": "create",
"api_key": "YOUR_API_KEY",
"api_secret_key": "YOUR_SECRET_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"mode": "test",
"marchant_id": "1001",
"amount": "2500.00",
"transaction_id": "CMD-20261118-0042",
"description": "Order #42",
"callback_url": "https://shop.example.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' => 'Order #42',
'callback_url' => 'https://shop.example.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: 'Order #42',
callback_url: 'https://shop.example.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://shop.example.com"],
"warning": null
}2. Show the form
On a website: embedded in your page
Add the HPay script and a placeholder. Pass the session_id created by your server to the page (never your keys). The form adjusts its own height.
The onSucces, onAnnulation and onErreur callbacks are for updating your page. They do not prove payment: wait for the step 3 confirmation before fulfilling.
In a mobile app
Load the session url in a WebView inside your app: the customer stays in your app and no external browser opens. Set return_url and cancel_url, then intercept navigation to those addresses to close the WebView.
In full page mode, HPay appends session_id, transaction_id and status to return_url.
<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/thank-you';
},
onAnnulation: function () { /* back to the cart */ },
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() is the same as HPay.monter(), and HPay.open(session) opens the form as a full page.
3. Confirm the payment on your server
The signed notification
As soon as the payment succeeds or fails, HPay sends a JSON POST request to your callback_url. Reply with a 2xx status.
Always verify the signature before fulfilling:
- read the X-HPay-Timestamp and X-HPay-Signature headers;
- compute the hex HMAC-SHA256 of “timestamp.raw body” with your api_secret_key;
- compare in constant time, and reject a timestamp older than 5 minutes;
- check that transaction_id, amount and currency match your order.
Or query the session
At any time your server can ask for a session's status with action=retrieve. Useful if a notification did not reach you.
<?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') {
// Check transaction_id, amount and currency, then mark the order as paid (once only).
}
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') { /* mark the order as paid */ }
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", … }Session statuses
| status | Meaning |
|---|---|
open | Created; the customer has not entered a card yet. |
pending_confirmation | Card and PIN accepted; confirmation code sent to the customer. |
paid | Payment accepted: you can fulfil the order. |
failed | Payment declined (insufficient balance, blocked card…). |
canceled | The customer cancelled. |
expired | Not paid in time. Create a new session. |
Error codes
Every response contains success, error_code and message. When a field is at fault, field names it.
| error_code | HTTP | Cause |
|---|---|---|
1 | 405 | Method other than POST. |
2 | 400 | Invalid JSON body. |
3 | 400 | Missing field or unknown action. |
4 | 401 | Invalid API keys. |
5 | 400 | Wrong mode, or different from your keys' mode. |
6 | 400 | Unknown or disabled marchant_id. |
7 | 400 | Invalid amount. |
8 | 400 / 409 | transaction_id invalid or already used. |
9 | 400 | URL is not https. |
10 | 404 | Session not found. |
503 | 503 | Service temporarily unavailable: retry. |
During payment, the customer sees declines directly (wrong PIN, insufficient balance). After 5 wrong PINs within 15 minutes, the card is paused for 15 minutes, then works again by itself.
Test mode
With test-mode keys, sessions start with cs_test_ and the payment page shows “TEST MODE”. Ask HPay support for a test card to try the whole flow, confirmation code included. Go live only once signature verification works.
Best practices
- Keep api_secret_key on your server, in an environment variable. Never in a web page, an app or a code repository.
- Never ask for the card or PIN in your own forms: only the HPay form should receive them.
- Fulfil on the signed notification or on action=retrieve, not on onSucces or return_url alone.
- Process each notification only once: the same one may arrive twice.
- Use a unique transaction_id per order: HPay rejects duplicates, which prevents double charges.