Skip to content
HPay Developers
Français
Merchant API reference

Transfers

Send a transfer

POSThttps://api.hpay.cash/transfert/

Token: action transfert, valid for 5 min

Card-funded types

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"
}'
Response
{
  "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_codeHTTPCause
300200Unknown API key.
301200Invalid token.
302200Token expired.
401200Mode does not match your keys.
500200Wrong secret or public key.
600 / 603200Token issued for another action.
601200Unknown point of sale.
602200Point of sale not activated.
604200transaction_id already used.
30 / 10000200Unknown transfert_type, or empty beneficiary details.
31200Invalid sender card (or unknown point of sale for MARCHAND_CLIENT).
32200Card or point of sale not activated.
33200Wrong PIN (or point of sale suspended for MARCHAND_CLIENT).
21114295 wrong PINs within 15 minutes: card paused for 15 minutes.
34200Sender HPay account not confirmed.
30010200Sender and beneficiary cards are the same.
36200Insufficient balance.
37200Beneficiary not found (HPAY_HPAY).
3900200Unknown destination country.
44200Beneficiary currency not supported.

Pay out a withdrawal code

POSThttps://api.hpay.cash/withdraw/withdraw_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"
}'
Response
{
  "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_codeHTTPCause
100200Invalid JSON body.
30200Unknown API key.
403200Point of sale not found.
404200Invalid or already used code.
505200Sender not found: contact HPay.
500 / 501200Conversion or recording error: contact HPay before retrying.

Transfer history

POSThttps://api.hpay.cash/transfertHistory/

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": ""
}'
Response
{
  "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_codeHTTPCause
30200Unknown transfert_type.
300200Wrong API key or public key.

Next : Bank payouts →