Skip to content
HPay Developers
Français
Merchant API reference

Payments

Card payment at a terminal

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

Token: action payment, valid for 5 min

Approved payment terminals only

This endpoint receives the customer's card and PIN. It is reserved for physical payment terminals approved by HPay, where customers type their own PIN. For a website or app, use the payment gateway: you never handle the PIN.

Debits the customer's HPay card and credits the point of sale. The amount is in your Business account currency; if the customer's account uses another currency, HPay converts automatically. All 14 keys must be present and non-empty.

Parameters (JSON)

api_keyrequiredstring Your API key.
api_public_keyrequiredstring Your public key.
tokenrequiredstring Token from /token/ with the stated action.
moderequiredstring test or live, matching your keys.
actionrequiredstring payment
marchant_idrequiredstring Point-of-sale number (1 to 15 characters).
amountrequirednumber Amount with a decimal point (5.50, not 5,50), at most 2 decimals.
hpay_cardrequiredstring HPay card number (16 digits, starts with 57).
hpay_card_pinrequiredstring PIN entered by the customer on the terminal. Never store it.
transaction_idrequiredstring Your unique reference: 1 to 64 characters (letters, digits, - and _).
payment_linkrequiredstring Always "no".
callback_urlrequiredstring Not used for a terminal payment: send "no".
on_success_urlrequiredstring Not used: send "no".
on_error_urlrequiredstring Not used: send "no".

Safe retries: if the response does not reach you, resend exactly the same request (same transaction_id, amount and card) with a new token. If the payment was already recorded, HPay replies success: true and already_processed: true, without charging twice. In test mode nothing is debited, but the transaction is recorded.

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"
}'
Response
{
  "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
}

Errors specific to this endpoint

error_codeHTTPCause
3000400Zero or negative amount.
3001400Invalid amount (comma instead of point, too large).
330400Invalid transaction_id.
70200Wrong card or PIN.
21114295 wrong PINs within 15 minutes: card paused for 15 minutes. The cardholder is notified by email.
701200Card suspended.
80400Insufficient customer balance.
90400Customer account inactive.
1100400Point of sale unknown, inactive or owned by another account.
409409transaction_id already used with different data, or refunded.
503503Service temporarily unavailable (exchange rate, accounting).
500500Uncertain outcome: check with /historiques/ before retrying.

Refund a payment

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

Token: action refund, valid for 5 min

Cancels a payment and returns the full amount to the customer. Partial refunds are not available. Note: this endpoint's error codes do not follow the same numbering as the others.

Parameters (JSON)

api_keyrequiredstring Your API key.
api_public_keyrequiredstring Your public key.
tokenrequiredstring Token from /token/ with the stated action.
moderequiredstring test or live, matching your keys.
actionrequiredstring refund
transaction_idrequiredstring Reference of the payment to refund.
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"
}'
Response
{
  "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
}

Errors specific to this endpoint

error_codeHTTPCause
30200Unknown API key.
40200Invalid transaction_id.
50200Invalid token.
60200Mode does not match your keys.
70200Wrong secret or public key.
80200Token expired or issued for another action.
90400Payment not found, already refunded or in another mode.
409409Older payment that HPay must reconcile before refund.
503503Service temporarily unavailable.

Payment history

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

Token: action history, valid for 15 min

Lists your payments, newest first. All 9 keys must be sent; filters may be empty. There is no pagination: keep the date range short.

Parameters (JSON)

main_api_keyrequiredstring Your API key (same value as api_key).
tokenrequiredstring Token from /token/ with the stated action.
moderequiredstring test or live.
marchant_idmay be emptystring Filter: one point of sale.
currencymay be emptystring Filter: customer currency (HTG, USD…).
transaction_idmay be emptystring Filter: one reference.
date_frommay be emptystring Start, inclusive, YYYY-MM-DD (with date_to).
date_tomay be emptystring End, inclusive, YYYY-MM-DD.
payment_methodemay be emptystring Reserved: send an empty value.

No result: success is false and error_code is "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": ""
}'
Response
{
  "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",
        "…": "…"
      }
    }
  ]
}

Errors specific to this endpoint

error_codeHTTPCause
30200Unknown API key.
330200transaction_id must be an integer for this filter.
111200No payment for these filters.

Next : Points of sale →