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/quotes —— 不要拿汇率自己算， 实付 = 上游报价 + 我方成本保护 + 溢价 + 手续费，你算不出来。 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 'x-auth-token: Bearer $TOKEN' \
  -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: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/qrpay/decode",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "content-type": "application/json",
    },
    json={
      "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zise.com/v1/qrpay/decode",
    strings.NewReader(`{
  "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
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/decode"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/qrpay/decode');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "code_value": "00020101021229300012D156000000000510A93FO3230Q..."
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "payee": "Bangkok Coffee Co.",
  "currency": "THB",
  "amount": "",
  "amount_editable": true,
  "min_amount": "1.00",
  "max_amount": "50000.00",
  "required_payer_fields": []
}