Skip to content
HPay Developers
Français
Merchant API reference

Deposits and withdrawals

Deposit to a card

POSThttps://api.hpay.cash/deposit/

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"
}'
Response
{
  "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_codeHTTPCause
21200Zero or negative amount.
330200transaction_id must be an integer.
70200Unknown card.
90200Customer account suspended.
702200Point of sale not found.
704200Insufficient point-of-sale balance.
705200Amount too small: the fee exceeds the deposit.
7041200No exchange rate for these currencies.
160200transaction_id already used.

Withdrawal from a card

POSThttps://api.hpay.cash/withdraw/

Token: action withdraw, 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.

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"
}'
Response
{
  "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_codeHTTPCause
21200Zero or negative amount.
330200transaction_id must be an integer.
70200Unknown card.
701200Wrong PIN.
21112005 wrong PINs within 15 minutes: card paused for 15 minutes.
90200Customer account suspended.
702200Point of sale not found.
704200Insufficient customer balance (amount + fee).
7041200No exchange rate for these currencies.
160200transaction_id already used.

Deposit and withdrawal history

POSThttps://api.hpay.cash/depotRetraitHistory/

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"
}'
Response
{
  "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_codeHTTPCause
300200Wrong API key or public key.
3001200Wrong point of sale.

Next : Cards →