解码收款二维码

解析 PIX 二维码内容。

接口

POST /cashin/pix/decode-qrcode

认证

Merchant Credential。详见 认证。

接口背景

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

接口请求字段

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

请求示例

POST /cashin/pix/decode-qrcode 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>"

请求体示例：

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

接口响应字段

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

字段名	类型	说明
status	int	响应码
msg	string	与 status 对应
data	object	解码结果；请求在认证或协议解析阶段失败时可能不返回。
data.type	string	二维码类型，见下表。
data.amount	decimal 或 null	二维码金额，单位为 BRL；未提供金额信息时为 null。
data.allowsChangeAmount	boolean 或 null	是否允许修改金额；true 表示允许，false 表示不允许，null 表示未提供。
data.toPix	string	收款方 Pix Key；未提供时为空字符串。
data.toPixType	string	收款方 Pix Key 类型；未提供时为空字符串。
data.toIspb	string	收款机构 ISPB 编码；按字符串处理以保留前导零，未提供时为空字符串。
data.toName	string	收款方名称；未提供时为空字符串。
data.toCpfCnpj	string	收款方 CPF 或 CNPJ；可能经过脱敏，未提供时为空字符串。
data.agency	string	收款银行分行号；未提供时为空字符串。
data.toAccount	string	收款账户号；未提供时为空字符串。

二维码类型与金额

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

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

响应示例

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

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