Payments
Card payment at a terminal
Token: action payment, valid for 5 min
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"
}'{
"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"
}{
"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_code | HTTP | Cause |
|---|---|---|
3000 | 400 | Zero or negative amount. |
3001 | 400 | Invalid amount (comma instead of point, too large). |
330 | 400 | Invalid transaction_id. |
70 | 200 | Wrong card or PIN. |
2111 | 429 | 5 wrong PINs within 15 minutes: card paused for 15 minutes. The cardholder is notified by email. |
701 | 200 | Card suspended. |
80 | 400 | Insufficient customer balance. |
90 | 400 | Customer account inactive. |
1100 | 400 | Point of sale unknown, inactive or owned by another account. |
409 | 409 | transaction_id already used with different data, or refunded. |
503 | 503 | Service temporarily unavailable (exchange rate, accounting). |
500 | 500 | Uncertain outcome: check with /historiques/ before retrying. |
Refund a payment
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"
}'{
"api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "refund",
"transaction_id": "TPE-20261118-0042"
}{
"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_code | HTTP | Cause |
|---|---|---|
30 | 200 | Unknown API key. |
40 | 200 | Invalid transaction_id. |
50 | 200 | Invalid token. |
60 | 200 | Mode does not match your keys. |
70 | 200 | Wrong secret or public key. |
80 | 200 | Token expired or issued for another action. |
90 | 400 | Payment not found, already refunded or in another mode. |
409 | 409 | Older payment that HPay must reconcile before refund. |
503 | 503 | Service temporarily unavailable. |
Payment history
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": ""
}'{
"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": ""
}{
"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_code | HTTP | Cause |
|---|---|---|
30 | 200 | Unknown API key. |
330 | 200 | transaction_id must be an integer for this filter. |
111 | 200 | No payment for these filters. |