全球收单 › API 参考 › 扫码付

扫码付款（先锁钱再放行；processing = 结果不明，等 webhook）

POST /v1/qrpay/payments scope: qrpay:write

代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key 动钱 · 锁定会员该资产的可用余额（先锁钱，再通知上游放行）

这个端点会动钱

失败处置见下方响应表。超时（504）用同一把幂等键重试——我方可能已经处理完；业务失败要换新键，同键会原样返回那次失败。

我方从会员的数字资产余额扣一笔，上游把等值法币付给收款商户。

⚠ 先调 POST /v1/qrpay/quotes 做确认页。 直接调这一条等于让用户

在钱已经锁掉之后才第一次看见金额。本条自己会重报一次价再锁钱，

所以实扣金额可能与报价差几个最小单位 —— 以本条的响应为准。

顺序不可换：先锁钱，再通知上游放行。 后者的语义是「我方已经把钱

扣下来了，请放行」—— 颠倒过来就是上游放了行而我方没锁到钱。

⚠⚠ 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`）。不传 = 按该会员的支付优先级自动挑。⚠ 指定了一个这次报不出价的资产会直接拒，不会回落到自动挑。

响应

201已锁钱并已把请求发给上游。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"
}

400已登记的对外码：qr_code_invalid 码解不出来 / 上游拒绝 · service_unavailable 没有可用上游、你的预付不足、或这条线未对你开启（三种同一响应，刻意不解释原因）· invalid_request · idempotency_key_required · idempotency_key_invalid · member_context_required · member_not_found ⚠ 还落在 500 api_error：会员余额不足 · 没有可扣款的资产（上游给的币我方一个都没上架，或指定的 preferred_asset 这次没有报价）· 低于起付额 · 超单笔上限 · 超日累计额 · 触发实名门槛 · 会员被拉黑 / 账户冻结 / 卡资金保护中 · 该走廊未开通 · 金额超出这张码允许的范围。

409idempotency_key_reused · idempotency_in_progress

会触发的事件

qrpay.order.completed qrpay.order.failed qrpay.order.refunded

绿 = 终局且是好消息 · 红 = 终局且要处置 · 紫 = 中间态。点进去看事件体与验签。

请求

curl -X POST 'https://api.zise.com/v1/qrpay/payments' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -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: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "code_value": "00020101021229300012D156000000000510A93FO3230Q...",
    "currency": "THB",
    "amount": "250.00",
    "preferred_asset": "USDT"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();

import requests

res = requests.post(
    "https://api.zise.com/v1/qrpay/payments",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "code_value": "00020101021229300012D156000000000510A93FO3230Q...",
      "currency": "THB",
      "amount": "250.00",
      "preferred_asset": "USDT"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()

req, _ := http.NewRequest("POST", "https://api.zise.com/v1/qrpay/payments",
    strings.NewReader(`{
  "code_value": "00020101021229300012D156000000000510A93FO3230Q...",
  "currency": "THB",
  "amount": "250.00",
  "preferred_asset": "USDT"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/qrpay/payments"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "code_value": "00020101021229300012D156000000000510A93FO3230Q...",
  "currency": "THB",
  "amount": "250.00",
  "preferred_asset": "USDT"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double

$ch = curl_init('https://api.zise.com/v1/qrpay/payments');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "code_value": "00020101021229300012D156000000000510A93FO3230Q...",
  "currency": "THB",
  "amount": "250.00",
  "preferred_asset": "USDT"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval

201

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

扫码付款（先锁钱再放行；processing = 结果不明，等 webhook）

前置条件

请求头

请求体

响应

会触发的事件