ADOPAY 开发者平台

外观

/cashin/pix/decode-qrcode-partner 解码收款二维码 ​

接口背景 ​

解析 Pix 收款二维码的码值字符串，获取二维码类型、金额、是否允许修改金额及收款方账户信息。接口只执行解码，不创建收款或付款订单，也不发起扣款。解码成功不表示已支付或支付一定能成功。

接口请求地址 ​

项目内容
请求方式POST
请求路径/cashin/pix/decode-qrcode-partner
Content-Typeapplication/json
接口用途解析 Pix 收款二维码

接口接入规范 ​

使用合作商的一级商户号及对应凭证进行认证。本接口无需传入商户订单号或 subMerchantNo。

接口请求字段 ​

字段名位置类型字段长度是否必填说明
X-Merchant-IdHeaderstring64是一级商户号，从请求头读取。
X-TimestampHeaderint19是Unix 秒级请求时间戳。
X-NonceHeaderstring64是请求防重放随机字符串。
DigestHeaderstring52是对实际发送的请求体计算摘要，格式为 SHA-256=<Base64摘要>。
AuthorizationHeaderstring不定长是ES256 请求签名信息，其中 keyId 为合作商密钥版本号。
qrcodeBodystring最多 16384 字节是完整的 Pix Copy and Paste 码值；不能为空或仅包含空白字符。传入二维码文本，不是图片、图片 URL 或图片 Base64。
payDateBodystring10否支付日期，格式为 YYYY-MM-DD，例如 2026-09-07；必须是有效日历日期。不传或传空字符串时不指定支付日期。

请求示例 ​

http
POST /cashin/pix/decode-qrcode-partner HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1788768000
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<Base64摘要>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

请求体示例：

json
{
  "qrcode": "00020126580014br.gov.bcb.pix01361234567890123456789012345678901234520400005303986540550.005802BR5925Example Company Name6014CIDADE EXEMPLO62070503***63045ABC",
  "payDate": "2026-09-07"
}

接口响应字段 ​

接口使用统一的 status、msg、data 响应结构。下表中的解码字段以成功响应为准；失败时即使返回 data，也不能作为有效解码结果使用。

字段名类型说明
statusint响应码
msgstring与 status 对应
dataobject解码结果；请求在认证或协议解析阶段失败时可能不返回。
data.typestring二维码类型，见下表。
data.amountdecimal 或 null二维码金额，单位为 BRL；未提供金额信息时为 null。
data.allowsChangeAmountboolean 或 null是否允许修改金额；true 表示允许，false 表示不允许，null 表示未提供。
data.toPixstring收款方 Pix Key；未提供时为空字符串。
data.toPixTypestring收款方 Pix Key 类型；未提供时为空字符串。
data.toIspbstring收款机构 ISPB 编码；按字符串处理以保留前导零，未提供时为空字符串。
data.toNamestring收款方名称；未提供时为空字符串。
data.toCpfCnpjstring收款方 CPF 或 CNPJ；可能经过脱敏，未提供时为空字符串。
data.agencystring收款银行分行号；未提供时为空字符串。
data.toAccountstring收款账户号；未提供时为空字符串。

二维码类型与金额 ​

type含义
STATIC静态二维码
DYNAMIC_IMMEDIATE即时支付动态二维码
DYNAMIC_CHARGE账单动态二维码

amount 或 allowsChangeAmount 为 null 时，不能将其视为金额为零或允许修改金额。若返回上述列表之外的类型，amount 和 allowsChangeAmount 为 null；请按未识别类型处理。

响应示例 ​

以下为静态二维码的示意响应；账户及身份信息均为示例数据。

json
{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "type": "STATIC",
    "amount": 125.50,
    "allowsChangeAmount": false,
    "toPix": "receiver@example.com",
    "toPixType": "EMAIL",
    "toIspb": "01234567",
    "toName": "Example Receiver",
    "toCpfCnpj": "123******01",
    "agency": "0001",
    "toAccount": "123456"
  }
}

失败处理 ​

  • qrcode 缺失、为空白或超过长度限制，或 payDate 日期不合法时，请修正请求后再调用。
  • 解码失败或返回无效结果时，接口返回失败响应；不要使用失败响应中的空字段继续付款。
  • 具体失败码以响应状态及实际响应为准。

相关接口 ​