Products
Developers
Resources
Company

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:

JSON
{
  "code": 0,
  "msg": "success",
  "data": {}
}

Rules:

  • code = 0 means success
  • code != 0 means failure
  • msg contains the reason. A failure message usually ends in | and a stable key (for example Order not found|orderNotFound); match on the code or the key, not on the text
  • data contains the business object on success and is omitted on failure
  • The HTTP status is 200 for 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:

codeMeaning
400Invalid request format
401Unauthorized
403Forbidden
422Business validation error, including duplicate merchant_order_no / merchant_refund_no
500Internal server error
1001Merchant account suspended
2002Order not found
2006Collection amount does not satisfy channel limits
3003Payment method not enabled or not currently available
4001Too many payment requests (HTTP 429); retry shortly
5001Duplicate payout order
5002Payout order not found
5004Insufficient payout balance
5007Payout method not available
5008Payout amount does not satisfy channel limits

Integration Recommendations

Idempotency

  • Enforce idempotency using merchant_order_no, merchant_refund_no, and merchant_payout_no
  • Notification handling should also be idempotent
  • If the same notification is received multiple times, return success after confirming the order is already processed
  • A repeated merchant_order_no or merchant_refund_no is rejected with code=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_no and merchant_refund_no share 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 FAILED as permanent in fulfilment logic; see Query Payment Order