# 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](https://www.hansapay.io/docs/what-to-expect)) 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`, 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](https://www.hansapay.io/docs/payments#query-payment-order)
