# cURL 联调

> 每个接口的签名 cURL 示例，适合在测试环境快速联调。

下面示例适合本地快速联调。

测试环境请使用测试卡 `4111111111111111`，有效期填写任意未来日期，CVC 填 `123`，见 [创建支付订单](https://www.hansapay.io/docs/zh/testing#create-payment-order)。

## 准备变量

```bash
BASE_URL="https://api.example.com/api/v1"
MERCHANT_ID="M123456"
SECRET_KEY="your_merchant_secret"
TIMESTAMP="$(date +%s)"
NONCE="8f31a2bc9d4e6f70"
```

## 创建支付订单

```bash
BODY='{"payment_method":"CARD","merchant_order_no":"M202406240001","trans_amount":{"currency":"USD","value":"99.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","card":{"card_number":"4111111111111111","cardholder_name":"JOHN DOE","exp_month":12,"exp_year":2028,"cvc":"123"},"billing_address":{"country":"US","first_name":"John","last_name":"Doe","email":"john@example.com","phone":"15551234567","state":"CA","city":"San Francisco","address":"Market Street","street_number":"1355","postal_code":"94103"},"device_ip":"1.1.1.1","client_ip":"1.1.1.1"}'

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 "${BASE_URL}/payments/create" \
  -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": 2006,
  "msg": "Amount is out of the allowed range|amountOutOfRange"
}
```

## 查询支付订单

```bash
BODY='{"merchant_order_no":"M202406240001"}'

TIMESTAMP="$(date +%s)"
NONCE="9a42b3cc7d8e9f10"
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 "${BASE_URL}/payments/query" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## 创建退款

```bash
BODY='{"original_merchant_order_no":"M202406240001","merchant_refund_no":"MR202406240001","refund_amount":"10.00","reason":"customer requested","notify_url":"https://merchant.example.com/callback/refund","metadata":"refund=manual"}'

TIMESTAMP="$(date +%s)"
NONCE="abcd1234ef567890"
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 "${BASE_URL}/refunds/create" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## 创建代付

```bash
BODY='{"payment_method":"CASH_APP","merchant_payout_no":"MP202406240001","trans_amount":{"currency":"USD","value":"88.50"},"payee":{"account_id":"$cashdemo","account_type":"CASHTAG","full_name":"John Doe","country":"US"},"memo":"settlement","notify_url":"https://merchant.example.com/callback/payout","metadata":"batch=20260624","client_ip":"1.1.1.1"}'

TIMESTAMP="$(date +%s)"
NONCE="11223344aabbccdd"
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 "${BASE_URL}/payouts/create" \
  -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": "CASH_APP",
    "payout_no": "P202406240001",
    "merchant_payout_no": "MP202406240001",
    "status": "PROCESSING",
    "trans_amount": {
      "currency": "USD",
      "value": "88.50"
    },
    "fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "total_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "next_action": "WAIT_NOTIFY",
    "created_at": "2026-06-24T12:00:00+08:00"
  }
}
```

## 查询代付

```bash
BODY='{"merchant_payout_no":"MP202406240001"}'

TIMESTAMP="$(date +%s)"
NONCE="22334455bbccddee"
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 "${BASE_URL}/payouts/query" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## 取消代付

```bash
BODY='{"merchant_payout_no":"MP202406240001","reason":"manual cancel"}'

TIMESTAMP="$(date +%s)"
NONCE="33445566ccddee77"
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 "${BASE_URL}/payouts/cancel" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## 代付预检查

```bash
BODY='{"payment_method":"PAYPAL","trans_amount":{"currency":"USD","value":"88.50"}}'

TIMESTAMP="$(date +%s)"
NONCE="44556677ddeeff88"
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 "${BASE_URL}/payouts/precheck" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```
