# Merchant API

> Integrate HansaPay from your server: card and wallet payments, refunds and signed notifications. Every endpoint is a JSON POST signed with HMAC-SHA256.

## Base URLs

- Test: `https://api-test.hansapay.io`
- Production: `https://api.hansapay.io`

Examples in the reference use `https://api.example.com` as a placeholder host.

## Quick start

A hosted checkout: send the order, redirect the payer to the returned `checkout_url`, and wait for the signed `payment.updated` notification.

### Request

```bash
BODY='{"payment_method":"CARD","merchant_order_no":"M202406240002","trans_amount":{"currency":"USD","value":"49.99"},"notify_url":"https://merchant.example.com/callback/payment","return_url":"https://merchant.example.com/pay/success","trade_info":{"goods_name":"VIP Membership","description":"Monthly subscription"},"metadata":"biz=member&uid=10001","client_ip":"203.0.113.10"}'

TIMESTAMP="$(date +%s)"
NONCE="$(openssl rand -hex 8)"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "https://api-test.hansapay.io/api/v1/payments/checkout" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

### Response

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202406240002",
    "merchant_order_no": "M202406240002",
    "status": "CHECKOUT_REQUIRED",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "next_action": "CHECKOUT_REQUIRED",
    "token": "5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
    "checkout_url": "https://cashier.example.com/pay/5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
    "created_at": "2026-06-24T10:05:00+08:00"
  }
}
```

## Endpoints

### Payment APIs

| Route | Description |
|---|---|
| [`POST /api/v1/payments/create`](https://www.hansapay.io/docs/payments#create-payment-order-unified-entry) | Direct payment creation |
| [`POST /api/v1/payments/checkout`](https://www.hansapay.io/docs/payments#checkout-payment) | Checkout payment creation |
| [`POST /api/v1/payments/query`](https://www.hansapay.io/docs/payments#query-payment-order) | Query payment order |

### Refund APIs

| Route | Description |
|---|---|
| [`POST /api/v1/refunds/create`](https://www.hansapay.io/docs/refunds#create-refund) | Create refund |
| [`POST /api/v1/refunds/query`](https://www.hansapay.io/docs/refunds#query-refund) | Query refund |

### Payout APIs

| Route | Description |
|---|---|
| [`POST /api/v1/payouts/create`](https://www.hansapay.io/docs/payouts#create-payout) | Create payout |
| [`POST /api/v1/payouts/query`](https://www.hansapay.io/docs/payouts#query-payout) | Query payout |
| [`POST /api/v1/payouts/cancel`](https://www.hansapay.io/docs/payouts#cancel-payout) | Cancel payout |
| [`POST /api/v1/payouts/precheck`](https://www.hansapay.io/docs/payouts#payout-balance-precheck) | Payout balance precheck |

Also available: the OpenAPI spec at https://www.hansapay.io/openapi.json
