Authentication
The merchant API is for your servers and approved payment terminals. To accept payments on a website or in an app, start with the payment gateway. See the gateway
Conventions
POSThttps://api.hpay.cash/…/
- Every request is a POST with a JSON body and a Content-Type: application/json header. Paths end with a slash and are case-sensitive.
- Send exactly the listed keys: an extra or missing key is rejected (errors 5 and 10). A key marked "may be empty" must still be sent, as "".
- A required value cannot be 0 or "0": it would be treated as empty (error 20).
- Amounts in the currency's main unit, with a decimal point: 5.50, not 5,50 or 550.
- One token per operation, requested just before, with the matching action. A "payment" token cannot be used for a refund.
- Exception: the gateway (/checkout/) and HPay top-ups (/topup/) use no token. Your three keys are sent in every request, from your server only.
- Always check success and error_code (0 = success). Many errors come with HTTP status 200. Some reads put these fields inside an info object.
- After a timeout or a 500 error, check the real state (history) before repeating a money operation.
- In test mode no money moves, but operations are recorded.
Common errors
These codes can be returned by every endpoint that uses a token (except refunds, which have their own numbering).
| error_code | Cause | What to do |
|---|---|---|
5 | Wrong number of keys. | Send exactly the listed keys. |
10 | Unexpected key. | Check key spelling. |
20 | Required value empty. | Fill in the value; message names the field. |
30 | Unknown API key. | Check api_key / main_api_key. |
31 | Truncated or invalid token. | Request a new token. |
32 | Token expired. | Request a new token. |
41 | Mode differs from your keys. | Align mode. |
50 | Wrong secret or public key. | Check your keys. |
60 | Token issued for another action. | Request a token with the right action. |
Get a token
POSThttps://api.hpay.cash/token/
Every operation needs a recent token specific to its action. It is created with your three keys and stays valid for 5 minutes (15 minutes for reads). Request a new one before each operation.
Parameters (JSON)
api_keyrequiredstring |
Your API key. |
api_secret_keyrequiredstring |
Your secret key. |
api_public_keyrequiredstring |
Your public key. |
moderequiredstring |
test or live, matching your keys. |
actionrequiredstring |
The target operation, stated on each endpoint: payment, refund, history, get_balance, submarchant, newaccount, deposit, withdraw, check-card, transfert, withdraw-code, addBank, list-banks, delete-bank, add-withdraw, all-withdraw, cancel-withdraw. |
curl -X POST https://api.hpay.cash/token/ \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"api_secret_key": "YOUR_SECRET_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"mode": "test",
"action": "payment"
}'{
"api_key": "YOUR_API_KEY",
"api_secret_key": "YOUR_SECRET_KEY",
"api_public_key": "YOUR_PUBLIC_KEY",
"mode": "test",
"action": "payment"
}Response
{
"success": true,
"message": "Token generated",
"token": "TVlYb2ZhZ0x…",
"livetime": "3mn",
"time_generated": 1763474820,
"error_code": 0
}Errors specific to this endpoint
| error_code | HTTP | Cause |
|---|---|---|
30 | 200 | Unknown API key. |
40 | 200 | Mode does not match your keys. |
50 | 200 | Wrong secret or public key. |
60 | 200 | Unknown action. |