Transfers
Send a transfer
Token: action transfert, valid for 5 min
HPAY_CLIENT and HPAY_HPAY receive the sender's card and PIN: they are reserved for approved terminals, like payments. After 5 wrong PINs within 15 minutes, the card is paused for 15 minutes (2111).
Three types, chosen with transfert_type. MARCHAND_CLIENT: the point of sale sends money from its balance to a phone; the beneficiary gets a withdrawal code. HPAY_CLIENT: the same, paid with the customer's HPay card. HPAY_HPAY: from HPay card to HPay card. All 15 keys must always be sent; those not used by the chosen type stay empty.
Parameters (JSON)
main_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 |
transfert |
marchant_idrequiredstring |
Point-of-sale number (1 to 15 characters). |
amountrequirednumber |
Amount sent, in the sender's currency. |
transaction_idrequiredstring |
Your unique reference. |
transfert_typerequiredstring |
MARCHAND_CLIENT, HPAY_CLIENT or HPAY_HPAY. |
sender_hpay_cardmay be emptystring |
Sender card (HPAY_CLIENT, HPAY_HPAY). |
sender_hpay_card_pinmay be emptystring |
Sender PIN (HPAY_CLIENT, HPAY_HPAY). Never store it. |
benef_hpay_cardmay be emptystring |
Beneficiary card (HPAY_HPAY). |
benef_telephonemay be emptystring |
Beneficiary phone (MARCHAND_CLIENT, HPAY_CLIENT). |
benef_country_namemay be emptystring |
Beneficiary country, full name (MARCHAND_CLIENT, HPAY_CLIENT). |
benef_full_namemay be emptystring |
Beneficiary name, optional. |
transaction_code is the code the beneficiary will show to collect the money. Give it to them yourself (receipt, message): do not rely on the SMS alone. HPAY_HPAY credits the beneficiary card directly and returns no code.
curl -X POST https://api.hpay.cash/transfert/ \
-H "Content-Type: application/json" \
-d '{
"main_api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "transfert",
"marchant_id": "1001",
"amount": "5000.00",
"transaction_id": "2026111800051",
"transfert_type": "MARCHAND_CLIENT",
"sender_hpay_card": "",
"sender_hpay_card_pin": "",
"benef_hpay_card": "",
"benef_telephone": "50937000000",
"benef_country_name": "Haiti",
"benef_full_name": "Jean Pierre"
}'{
"main_api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"token": "FRESH_TOKEN",
"mode": "test",
"action": "transfert",
"marchant_id": "1001",
"amount": "5000.00",
"transaction_id": "2026111800051",
"transfert_type": "MARCHAND_CLIENT",
"sender_hpay_card": "",
"sender_hpay_card_pin": "",
"benef_hpay_card": "",
"benef_telephone": "50937000000",
"benef_country_name": "Haiti",
"benef_full_name": "Jean Pierre"
}{
"success": true,
"message": "Money sent to 50937000000 Jean Pierre succesfully. …",
"transaction_id": "2026111800051",
"amount_transfered": "5000.00",
"fees": "…",
"total_paid": "…",
"destination": "Haiti",
"sender_currency": "HTG",
"beneficiary_currency": "HTG",
"submerchant_commission": "…",
"gestionnaire_commission": "…",
"commercial_commission": "…",
"transaction_code": "…",
"token_used": "…",
"transaction_date": "2026-11-18 17:10:00",
"mode": "test",
"error_code": 0
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
300 | 200 | Unknown API key. |
301 | 200 | Invalid token. |
302 | 200 | Token expired. |
401 | 200 | Mode does not match your keys. |
500 | 200 | Wrong secret or public key. |
600 / 603 | 200 | Token issued for another action. |
601 | 200 | Unknown point of sale. |
602 | 200 | Point of sale not activated. |
604 | 200 | transaction_id already used. |
30 / 10000 | 200 | Unknown transfert_type, or empty beneficiary details. |
31 | 200 | Invalid sender card (or unknown point of sale for MARCHAND_CLIENT). |
32 | 200 | Card or point of sale not activated. |
33 | 200 | Wrong PIN (or point of sale suspended for MARCHAND_CLIENT). |
2111 | 429 | 5 wrong PINs within 15 minutes: card paused for 15 minutes. |
34 | 200 | Sender HPay account not confirmed. |
30010 | 200 | Sender and beneficiary cards are the same. |
36 | 200 | Insufficient balance. |
37 | 200 | Beneficiary not found (HPAY_HPAY). |
3900 | 200 | Unknown destination country. |
44 | 200 | Beneficiary currency not supported. |
Pay out a withdrawal code
Token: action withdraw-code, valid for 5 min
A transfer beneficiary shows their code at the point of sale, which hands them the cash. HPay credits the point of sale with the amount, converted to its currency. A code can be used only once.
Parameters (JSON)
api_keyrequiredstring |
Your API key. |
tokenrequiredstring |
Token from /token/ with the stated action. |
marchant_idrequiredstring |
Point-of-sale number (1 to 15 characters). |
payment_coderequiredstring |
The code shown by the beneficiary. |
Check the beneficiary's identity (name and phone returned) before handing over the cash. After a timeout, do not retry: check the transfer history first.
curl -X POST https://api.hpay.cash/withdraw/withdraw_code/ \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"token": "FRESH_TOKEN",
"marchant_id": "1001",
"payment_code": "CODE_FROM_TRANSFER"
}'{
"api_key": "YOUR_API_KEY",
"token": "FRESH_TOKEN",
"marchant_id": "1001",
"payment_code": "CODE_FROM_TRANSFER"
}{
"success": true,
"message": "Retrait validé avec succès.",
"details": {
"id_transfert": "…",
"montant_original": "5000.00",
"montant_converti": "5000.00",
"taux_conversion": 1,
"gain_hpay": "…",
"nouveau_solde_sous_marchand": "…",
"devise_originale": "HTG",
"devise_convertie": "HTG",
"expediteur": {
"nom": "…",
"prenoms": "…",
"telephone": "…",
"email": "…"
},
"beneficiaire": {
"nom": "Jean Pierre",
"telephone": "50937000000"
}
},
"error_code": 0
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
100 | 200 | Invalid JSON body. |
30 | 200 | Unknown API key. |
403 | 200 | Point of sale not found. |
404 | 200 | Invalid or already used code. |
505 | 200 | Sender not found: contact HPay. |
500 / 501 | 200 | Conversion or recording error: contact HPay before retrying. |
Transfer history
No token
Read-only, no token. All 9 keys must be sent. Note that dates are called from_date and to_date here.
Parameters (JSON)
main_api_keyrequiredstring |
Your API key. |
api_public_keyrequiredstring |
Your public key. |
marchant_idrequiredstring |
The point of sale. |
moderequiredstring |
test or live, matching your keys. |
transfert_typerequiredstring |
MARCHAND_CLIENT, HPAY_CLIENT, HPAY_HPAY or ALL. |
from_datemay be emptystring |
Start, inclusive, YYYY-MM-DD. |
to_datemay be emptystring |
End, inclusive, YYYY-MM-DD. |
transaction_idmay be emptystring |
Filter: one reference. |
transaction_codemay be emptystring |
Filter: one withdrawal code. |
curl -X POST https://api.hpay.cash/transfertHistory/ \
-H "Content-Type: application/json" \
-d '{
"main_api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"marchant_id": "1001",
"mode": "live",
"transfert_type": "ALL",
"from_date": "2026-11-01",
"to_date": "2026-11-18",
"transaction_id": "",
"transaction_code": ""
}'{
"main_api_key": "YOUR_API_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"marchant_id": "1001",
"mode": "live",
"transfert_type": "ALL",
"from_date": "2026-11-01",
"to_date": "2026-11-18",
"transaction_id": "",
"transaction_code": ""
}{
"info": {
"success": true,
"message": "…",
"transaction_mode": "live",
"error_code": 0
},
"history": [
{
"transaction_id": "2026111800051",
"transaction_code": "…",
"mode": "live",
"transfert_type": "MARCHAND_CLIENT",
"transaction_date": "2026-11-18 17:10:00",
"beneficiary_info": {
"nom": "Jean Pierre",
"telephone": "50937000000"
},
"transaction_data": {
"amount_sent": "5000.00",
"fees": "…",
"total": "…",
"currency_from": "HTG",
"currency_to": "HTG",
"country_destination": "Haiti",
"amount_received": "…",
"…": "…"
}
}
]
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
30 | 200 | Unknown transfert_type. |
300 | 200 | Wrong API key or public key. |