HansaPay
Products
Developers
Resources
Company
Open an accountSign in
文档cURL 联调

入门

English

cURL 联调

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

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

测试环境请使用测试卡 4111111111111111，有效期填写任意未来日期，CVC 填 123，见 创建支付订单。

准备变量

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

创建支付订单

Shell
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":"[email protected]","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"
}

查询支付订单

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

创建退款

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

创建代付

Shell
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": 5007,
  "msg": "payment_method CASH_APP is not available for payouts|unsupportedPayoutMethod"
}

查询代付

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

取消代付

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

代付预检查

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