Z Zise Developers
/
API 参考 › 扫码付
POST /v1/qrpay/decode

解码收款码（纯读，不建单不锁钱）

Scope qrpay:write 代会员调用 · 必带 x-on-behalf-of

把用户扫到的码原文解出来，拿到收款方名称、币种与金额。

纯读：不建单、不锁钱、不占额度，所以也不需要幂等键。

⚠ amount_editable 才是「这张码要不要用户自己填金额」的事实源，

判据是上游有没有要求补报金额。不要用 amount == "" 去推——

那是同一件事的副作用，哪天上游对静态码回一个占位金额，你的推断就

静默反过来了。

⚠ isKYCUser 由我方按会员真实等级填，你不用传、也传不了。

上游把这一位的「空」当成已实名，所以省略等于替一个未实名的用户声明

他已实名 —— 那是合规问题，不是参数问题。

⚠ required_payer_fields 非空时，上游要求随单补报付款人信息。

但本期 POST /v1/qrpay/payments 没有提交这些字段的入参 ——

碰到非空的码，这一单在开放 API 上走不通，请走会员端。

（已报回我方。）

⚠ 解码失败与支付失败不是一回事：这一步还没动钱，网络层失败就是

真失败，直接拒，不存在「结果不明」。

前置条件

  • 扫码付这条线已对你开启，且我方至少有一个可用的上游
字段类型必填说明
x-on-behalf-of string 必填 谁在扫这张码。必填 —— 实名位按这个会员的真实等级填给上游。

请求体

字段类型必填说明
code_value string 必填 二维码原文（扫出来是什么就传什么，不要预处理）。

响应

200currency / amount / min_amount / max_amount 是收单侧法币 （上游最终付给收款商户的那个币），不是会员要扣的数字资产。 会员实扣多少要到 POST /v1/qrpay/payments 才知道。 amount 为空串 = 自定义金额码（你在支付时给出金额）。
{
  "payee": "Bangkok Coffee Co.",
  "currency": "THB",
  "amount": "",
  "amount_editable": true,
  "min_amount": "1.00",
  "max_amount": "50000.00",
  "required_payer_fields": []
}
400qr_code_invalid 码解不出来 / 不是我方支持的码制 / 上游拒绝 （三种同一响应）· service_unavailable 此刻没有可用上游 · member_context_required · member_not_found
403insufficient_scope —— 这把 Key 没有 qrpay:write
调用样例 
curl -X POST 'https://api.zise.com/v1/qrpay/decode' \
  -H 'authorization: Bearer $TOKEN' \
  -H 'x-zise-merchant: $MERCHANT_ID' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'content-type: application/json' \
  -d '{
    "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
  }'
const res = await fetch(
  "https://api.zise.com/v1/qrpay/decode",
  {
    method: "POST",
    headers: {
      "authorization": "Bearer $TOKEN",
      "x-zise-merchant": "MERCHANT_ID",
      "x-on-behalf-of": "MEMBER_ID",
      "content-type": "application/json"
    },
    body: JSON.stringify({
      "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
    }),
  },
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/qrpay/decode",
    headers={
        "authorization": "Bearer $TOKEN",
        "x-zise-merchant": "$MERCHANT_ID",
        "x-on-behalf-of": "$MEMBER_ID",
        "content-type": "application/json"
    },
    json={
        "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()