# 商户 API

> 在服务端接入 HansaPay：卡与钱包支付、退款及签名的异步通知。所有接口均为 JSON POST，并使用 HMAC-SHA256 签名。

## Base URL

- 测试环境: `https://api-test.hansapay.io`
- 生产环境: `https://api.hansapay.io`

文档中的示例统一使用 `https://api.example.com` 作为参考域名。

## 快速开始

收银台下单：提交订单，将付款人跳转到返回的 `checkout_url`，然后等待签名的 `payment.updated` 异步通知。

### 请求

```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"
```

### 响应

```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"
  }
}
```

## 接口列表

### 支付类

| 接口 | 说明 |
|---|---|
| [`POST /api/v1/payments/create`](https://www.hansapay.io/docs/zh/payments#create-payment-order-unified-entry) | 直连下单 |
| [`POST /api/v1/payments/checkout`](https://www.hansapay.io/docs/zh/payments#checkout-payment) | 收银台下单 |
| [`POST /api/v1/payments/query`](https://www.hansapay.io/docs/zh/payments#query-payment-order) | 查询支付订单 |

### 退款类

| 接口 | 说明 |
|---|---|
| [`POST /api/v1/refunds/create`](https://www.hansapay.io/docs/zh/refunds#create-refund) | 创建退款 |
| [`POST /api/v1/refunds/query`](https://www.hansapay.io/docs/zh/refunds#query-refund) | 查询退款 |

### 代付类

| 接口 | 说明 |
|---|---|
| [`POST /api/v1/payouts/create`](https://www.hansapay.io/docs/zh/payouts#create-payout) | 创建代付 |
| [`POST /api/v1/payouts/query`](https://www.hansapay.io/docs/zh/payouts#query-payout) | 查询代付 |
| [`POST /api/v1/payouts/cancel`](https://www.hansapay.io/docs/zh/payouts#cancel-payout) | 取消代付 |
| [`POST /api/v1/payouts/precheck`](https://www.hansapay.io/docs/zh/payouts#payout-balance-precheck) | 代付余额预检查 |

另见 OpenAPI 描述： https://www.hansapay.io/openapi.json
