Z Zise Developers
/
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.completedqrpay.order.failedqrpay.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"
}