Skip to content
HPay Developers
Français
Integration guide

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

  1. 1Your server Creates a session Amount and order reference, sent to HPay with your secret key.
  2. 2Your page Shows the form The HPay form appears in a frame on your page or inside your app.
  3. 3Your customer Pays on HPay Card, PIN, then a confirmation code received by email.
  4. 4HPay Notifies you Signed notification sent to your server: you fulfil the order.
You never handle card data

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:

ItemPurpose
api_keyIdentifies your account.
api_public_keyPublic key, sent with every call.
api_secret_keySecret key. It is also used to verify notification signatures. Keep it on your server only.
marchant_idNumber of the point of sale (terminal) receiving the money. You can have several.
modetest or live: must match the mode of your keys.
Declare your domains

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.

POSThttps://api.hpay.cash/checkout/
From your server only

This call contains your secret key: never make it from a browser or a mobile app.

Parameters (JSON)

actionrequiredcreate
api_key, api_secret_key, api_public_keyrequiredYour keys.
moderequiredtest or live
marchant_idrequiredThe point of sale receiving the money.
amountrequiredstringAmount, at most 2 decimals, in your Business account currency.
transaction_idrequiredYour unique order reference: 1 to 64 characters (letters, digits, - and _).
descriptionoptionalText shown to the customer (255 characters).
callback_urloptionalhttps address on your server that receives the notification. Strongly recommended.
return_url, cancel_urloptionalhttps 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"
  }'
Response
{
  "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>
English names available

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:

  1. read the X-HPay-Timestamp and X-HPay-Signature headers;
  2. compute the hex HMAC-SHA256 of “timestamp.raw body” with your api_secret_key;
  3. compare in constant time, and reject a timestamp older than 5 minutes;
  4. 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);
Notification body
{
  "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", … }

Session statuses

statusMeaning
openCreated; the customer has not entered a card yet.
pending_confirmationCard and PIN accepted; confirmation code sent to the customer.
paidPayment accepted: you can fulfil the order.
failedPayment declined (insufficient balance, blocked card…).
canceledThe customer cancelled.
expiredNot 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_codeHTTPCause
1405Method other than POST.
2400Invalid JSON body.
3400Missing field or unknown action.
4401Invalid API keys.
5400Wrong mode, or different from your keys' mode.
6400Unknown or disabled marchant_id.
7400Invalid amount.
8400 / 409transaction_id invalid or already used.
9400URL is not https.
10404Session not found.
503503Service 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