Getting started
中文Responses & errors
The response structure, error codes, and how to handle idempotency, amounts and status.
Common Response Structure
All merchant API business responses use:
{
"code": 0,
"msg": "success",
"data": {}
}Rules:
code = 0means successcode != 0means failuremsgcontains the reason. A failure message usually ends in|and a stable key (for exampleOrder not found|orderNotFound); match on the code or the key, not on the textdatacontains the business object on success and is omitted on failure- The HTTP status is
200for every signed response, including errors. Only authentication errors (401/403) and the payment rate limit (429, see Important Notes) use their own HTTP status
Common error codes:
| code | Meaning |
|---|---|
400 | Invalid request format |
401 | Unauthorized |
403 | Forbidden |
422 | Business validation error, including duplicate merchant_order_no / merchant_refund_no |
500 | Internal server error |
1001 | Merchant account suspended |
2002 | Order not found |
2006 | Collection amount does not satisfy channel limits |
3003 | Payment method not enabled or not currently available |
4001 | Too many payment requests (HTTP 429); retry shortly |
5001 | Duplicate payout order |
5002 | Payout order not found |
5004 | Insufficient payout balance |
5007 | Payout method not available |
5008 | Payout amount does not satisfy channel limits |
Integration Recommendations
Idempotency
- Enforce idempotency using
merchant_order_no,merchant_refund_no, andmerchant_payout_no - Notification handling should also be idempotent
- If the same notification is received multiple times, return
successafter confirming the order is already processed - A repeated
merchant_order_noormerchant_refund_nois rejected withcode=422; HansaPay does not return the original response. If a create request times out, query by your number before retrying with a new one - A request that fails after HansaPay recorded it (for example a declined card) still uses up its number
merchant_order_noandmerchant_refund_noshare one namespace: do not reuse a refund number as an order number
Amount Handling
- Always use strings for request amounts
- Do not use floating-point arithmetic for money
- Use decimal libraries on the merchant side
Status Handling
- Treat asynchronous notifications as the final source of truth
- Query APIs are for reconciliation and fallback
- If direct payment returns
SUCCESS, you should still keep notification handling in place - Do not treat a card payment's
FAILEDas permanent in fulfilment logic; see Query Payment Order
