Deposits and withdrawals
Deposit to a card
Token: action deposit, valid for 5 min
The customer hands cash to the point of sale, which credits their HPay card. The point of sale is debited the amount; the customer receives the amount minus the deposit fee (currently 1 %, set by HPay). Part of the fee goes to the point of sale.
Parameters (JSON)
main_api_keyrequiredstring |
Your API key. |
public_keyrequiredstring |
Your public key (name specific to this endpoint). |
tokenrequiredstring |
Token from /token/ with the stated action. |
moderequiredstring |
test or live, matching your keys. |
actionrequiredstring |
deposit |
marchant_idrequiredstring |
Point-of-sale number (1 to 15 characters). |
amountrequirednumber |
Amount handed over by the customer. |
hpay_cardrequiredstring |
HPay card number (16 digits, starts with 57). |
transaction_idrequiredstring |
Unique reference, integer. |
curl -X POST https://api.hpay.cash/deposit/ \
-H "Content-Type: application/json" \
-d '{
"main_api_key": "YOUR_API_KEY",
"public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "deposit",
"marchant_id": "1001",
"amount": "1000.00",
"hpay_card": "5700123456783456",
"transaction_id": "2026111800042"
}'{
"main_api_key": "YOUR_API_KEY",
"public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "deposit",
"marchant_id": "1001",
"amount": "1000.00",
"hpay_card": "5700123456783456",
"transaction_id": "2026111800042"
}{
"success": true,
"message": "…",
"transaction_id": "2026111800042",
"amount_topuped": "1000.00",
"amount_credited": 990.0,
"hpay_fees": 10.0,
"marchant_gain": 5.0,
"marchant_currency": "HTG",
"payment_date": "2026-11-18 16:00:00",
"transaction_mode": "test",
"token_used": "…",
"error_code": 0
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
21 | 200 | Zero or negative amount. |
330 | 200 | transaction_id must be an integer. |
70 | 200 | Unknown card. |
90 | 200 | Customer account suspended. |
702 | 200 | Point of sale not found. |
704 | 200 | Insufficient point-of-sale balance. |
705 | 200 | Amount too small: the fee exceeds the deposit. |
7041 | 200 | No exchange rate for these currencies. |
160 | 200 | transaction_id already used. |
Withdrawal from a card
Token: action withdraw, 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.
The customer withdraws cash at the point of sale. Their card is debited the amount plus the withdrawal fee (currently 2 %, set by HPay); the point of sale is credited the amount and a share of the fee.
Parameters (JSON)
main_api_keyrequiredstring |
Your API key. |
public_keyrequiredstring |
Your public key. |
tokenrequiredstring |
Token from /token/ with the stated action. |
moderequiredstring |
test or live, matching your keys. |
actionrequiredstring |
withdraw |
marchant_idrequiredstring |
Point-of-sale number (1 to 15 characters). |
amountrequirednumber |
Amount handed to the customer, before fees. |
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 |
Unique reference, integer. |
The name amount_topuped is kept as is for withdrawals.
curl -X POST https://api.hpay.cash/withdraw/ \
-H "Content-Type: application/json" \
-d '{
"main_api_key": "YOUR_API_KEY",
"public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "withdraw",
"marchant_id": "1001",
"amount": "1000.00",
"hpay_card": "5700123456783456",
"hpay_card_pin": "••••",
"transaction_id": "2026111800043"
}'{
"main_api_key": "YOUR_API_KEY",
"public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "withdraw",
"marchant_id": "1001",
"amount": "1000.00",
"hpay_card": "5700123456783456",
"hpay_card_pin": "••••",
"transaction_id": "2026111800043"
}{
"success": true,
"message": "…",
"transaction_id": "2026111800043",
"amount_topuped": "1000.00",
"hpay_fees": 20.0,
"marchant_gain": 10.0,
"master_marchant_gain": 0.0,
"marchant_currency": "HTG",
"client_currency": "HTG",
"payment_date": "2026-11-18 16:05:00",
"transaction_mode": "test",
"token_used": "…",
"error_code": 0
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
21 | 200 | Zero or negative amount. |
330 | 200 | transaction_id must be an integer. |
70 | 200 | Unknown card. |
701 | 200 | Wrong PIN. |
2111 | 200 | 5 wrong PINs within 15 minutes: card paused for 15 minutes. |
90 | 200 | Customer account suspended. |
702 | 200 | Point of sale not found. |
704 | 200 | Insufficient customer balance (amount + fee). |
7041 | 200 | No exchange rate for these currencies. |
160 | 200 | transaction_id already used. |
Deposit and withdrawal history
No token
Read-only, no token: the API key and public key are enough. All 10 keys must be sent; filters may be empty, but the point of sale and mode are required.
Parameters (JSON)
main_api_keyrequiredstring |
Your API key. |
api_public_keyrequiredstring |
Your public key. |
transaction_typemay be emptystring |
deposit for deposits, withdraw for withdrawals, empty for both. |
moderequiredstring |
test or live. |
marchant_idrequiredstring |
The point of sale (one call per point of sale). |
client_phone_numbermay be emptystring |
Filter: customer phone. |
currencymay be emptystring |
Filter: currency. |
transaction_idmay be emptystring |
Filter: one reference. |
date_frommay be emptystring |
Start, inclusive, YYYY-MM-DD. |
date_tomay be emptystring |
End, inclusive, YYYY-MM-DD. |
curl -X POST https://api.hpay.cash/depotRetraitHistory/ \
-H "Content-Type: application/json" \
-d '{
"main_api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"transaction_type": "deposit",
"mode": "live",
"marchant_id": "1001",
"client_phone_number": "",
"currency": "",
"transaction_id": "",
"date_from": "2026-11-01",
"date_to": "2026-11-18"
}'{
"main_api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"transaction_type": "deposit",
"mode": "live",
"marchant_id": "1001",
"client_phone_number": "",
"currency": "",
"transaction_id": "",
"date_from": "2026-11-01",
"date_to": "2026-11-18"
}{
"info": {
"success": true,
"message": "…",
"transaction_mode": "live",
"error_code": 0,
"result_count": 1
},
"history": [
{
"transaction_id": "2026111800042",
"transaction_type": "deposit",
"transaction_date": "2026-11-18 16:00:00",
"transaction_data": {
"amount_sent": "1000.00",
"fees": "10.00",
"total": "…",
"currency_from": "HTG",
"currency_to": "HTG",
"merchant_commission": "5.00",
"…": "…"
}
}
]
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
300 | 200 | Wrong API key or public key. |
3001 | 200 | Wrong point of sale. |