/v1/qrpay/payments
扫码付款（先锁钱再放行；processing = 结果不明，等 webhook）
qrpay:write
代会员调用 · 必带 x-on-behalf-of
需 x-idempotency-key
动钱 · 锁定会员该资产的可用余额（先锁钱，再通知上游放行）
失败处置见下方响应表。超时（504）用同一把幂等键重试——我方可能已经处理完；业务失败要换新键，同键会原样返回那次失败。
我方从会员的数字资产余额扣一笔，上游把等值法币付给收款商户。
顺序不可换：先锁钱，再通知上游放行。 后者的语义是「我方已经把钱
扣下来了，请放行」—— 颠倒过来就是上游放了行而我方没锁到钱。
⚠⚠ status: "processing" 不是失败，是「结果不明」。
我方通知上游那一步网络层出错时，请求可能已经落地、上游可能已经放行 ——
所以我方绝不解冻，落 processing 交给查证与巡检。
你必须等 webhook（或按订单号轮询），不许自己判失败、不许自动重下一单。
自动重下的后果是同一次消费扣两笔。
status 取值：pending（极短暂，已锁钱未通知上游）/ processing /
completed / failed / expired / canceled / refunded。
⚠ completed 不是绝对终态 —— 退款会把它推到 refunded。
认不出的值原样存下并告警，不要 default。
⚠ 扣款币种不由你指定。 我方按该会员自己的支付设置里的优先级挑。
preferred_asset 只是「优先试这个」，且**指定了一个上游这次报不出价
的资产时会直接拒，不会静默换一个**（悄悄换个币扣钱是替用户做决定）。
⚠ currency / amount 只在自定义金额码上传，且是收单侧法币
的币种与金额。固定金额码上传了等于替商户改价 —— 我方会照传给上游，
对不上就被上游拒。
⚠ 我方报给上游的金额是上游自己那份报价的原文，不是会员实付总额
（实付 = 上游报价 + 我方成本保护 + 溢价 + 手续费，天然更大）。
所以响应里的 customer_total 与 acquirer_amount 不是同一个数、
也不是同一个币。
⚠ 这条线没有退款端点，也没有撤销 —— 上游的接口清单里就没有。
我方后台也没有「发起退款」。退款只会由上游侧发起，届时你收到
qrpay.order.refunded。
前置条件
- 扫码付这条线已对你开启，且我方至少有一个可用上游
- 这张码的码制我方支持（见
GET /v1/qrpay/schemes） - 会员至少有一个可扣款资产余额充足，且未超单笔 / 日累计限额
- 你的预付账户在该资产上有足够余额
请求头
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
x-on-behalf-of |
string | 必填 | 谁在付款。扣款优先级取这个会员自己的支付设置。 |
x-idempotency-key |
string | 必填 | UUID。同键重投拿回同一单。收到 504 / 网络超时时用同一把键 重投；收到明确的业务失败要换新键（同键会原样回放那次失败）。 |
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code_value |
string | 必填 | 二维码原文。与解码时传的那一份一致。 |
currency |
string | 可选 | 收单侧法币币种（如 THB）。只在自定义金额码上传，
固定金额码上不许传。 |
amount |
string | 可选 | 收单侧法币金额（如 "250.00"），不是数字资产数量。
只在自定义金额码上传。位数由该法币决定，不是 ledger_scale。 |
preferred_asset |
string | 可选 | 优先用哪个资产扣款（如 USDT）。不传 = 按该会员的支付
优先级自动挑。⚠ 指定了一个这次报不出价的资产会直接拒，
不会回落到自动挑。 |
响应
customer_total 与 fee 是定点十进制串
（位数 = 该资产 ledger_scale，这里不下发 scale，按 asset 查）。
acquirer_currency / acquirer_amount 是收单侧法币那一端。
⚠ 201 不代表支付成功 —— 看 status。processing 就是等 webhook。{
"id": "qrp_9f2c1b40-0e2a-4d7c-9d21-6f0c1c3e5a11",
"status": "processing",
"asset": "USDT",
"customer_total": "128.500000",
"fee": "0.500000",
"payee": "Bangkok Coffee Co.",
"acquirer_currency": "THB",
"acquirer_amount": "4500.00"
}qr_code_invalid 码解不出来 / 上游拒绝 ·
service_unavailable 没有可用上游、你的预付不足、或这条线未对你
开启（三种同一响应，刻意不解释原因）· invalid_request ·
idempotency_key_required · idempotency_key_invalid ·
member_context_required · member_not_found
⚠ 还落在 500 api_error：会员余额不足 · 没有可扣款的资产
（上游给的币我方一个都没上架，或指定的 preferred_asset 这次
没有报价）· 低于起付额 · 超单笔上限 · 超日累计额 ·
触发实名门槛 · 会员被拉黑 / 账户冻结 / 卡资金保护中 ·
该走廊未开通 · 金额超出这张码允许的范围。idempotency_key_reused · idempotency_in_progress触发的事件
curl -X POST 'https://api.zise.com/v1/qrpay/payments' \
-H 'authorization: Bearer $TOKEN' \
-H 'x-zise-merchant: $MERCHANT_ID' \
-H 'x-on-behalf-of: $MEMBER_ID' \
-H 'x-idempotency-key: $(uuidgen)' \
-H 'content-type: application/json' \
-d '{
"code_value": "00020101021229300012D156000000000510A93FO3230Q...",
"currency": "THB",
"amount": "250.00",
"preferred_asset": "USDT"
}'const res = await fetch(
"https://api.zise.com/v1/qrpay/payments",
{
method: "POST",
headers: {
"authorization": "Bearer $TOKEN",
"x-zise-merchant": "MERCHANT_ID",
"x-on-behalf-of": "MEMBER_ID",
"x-idempotency-key": "crypto.randomUUID()",
"content-type": "application/json"
},
body: JSON.stringify({
"code_value": "00020101021229300012D156000000000510A93FO3230Q...",
"currency": "THB",
"amount": "250.00",
"preferred_asset": "USDT"
}),
},
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();import requests
res = requests.post(
"https://api.zise.com/v1/qrpay/payments",
headers={
"authorization": "Bearer $TOKEN",
"x-zise-merchant": "$MERCHANT_ID",
"x-on-behalf-of": "$MEMBER_ID",
"x-idempotency-key": "$(uuidgen)",
"content-type": "application/json"
},
json={
"code_value": "00020101021229300012D156000000000510A93FO3230Q...",
"currency": "THB",
"amount": "250.00",
"preferred_asset": "USDT"
},
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()