解码 Pix QR Code

解码 Pix QR Code，返回 payload 中包含的数据。不会对目标账户执行 DICT 查询，也不会持久化所查询的 QR Code — 适用于支付决策前的预览流程。

Request

ENDPOINT

/pix/decode_qrcode_payload

METHOD

POST

Request Body

{
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD"
}

Body 参数

字段	类型	描述	字符数
`qr_code_payload` *	string	Pix 复制粘贴	-

Response

STATUS

200

Response Body: 静态 QR Code

{
  "qr_code_type": "static",
  "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
  "pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
  "transfer_amount": "30.00",
  "additional_data": null,
  "qr_code_data": {
    "target_pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
    "amount": "30.00",
    "receiver_conciliation_id": "***",
    "additional_data": [],
    "category_code": "0000",
    "city": "saopaulo",
    "postal_code": null,
    "reusable_qrcode": "no"
  }
}

STATUS

200

Response Body: 动态 QR Code — 即时支付

{
  "qr_code_type": "dynamic_instant",
  "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
  "pix_key": "teste.cobrancapix@gmail.com.br",
  "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
  "amount": "9367.61",
  "status": "ATIVA",
  "qr_code_data": {
    "target_pix_key": "teste.cobrancapix@gmail.com.br",
    "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
    "amount": "9367.61",
    "can_change": "no",
    "expiration_seconds": 201574,
    "created_at": "2023-03-13T19:00:28.440Z",
    "presented_at": "2023-03-14T19:07:48.729Z",
    "question_to_payer": "Liquidacao de Parcelas",
    "status": "ATIVA",
    "revision": 0,
    "category_code": "0000",
    "city": "RIO DE JANEIRO",
    "postal_code": null,
    "reusable_qrcode": "no",
    "receiver_url": "qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a90000",
    "additional_data": [],
    "payer_name": "ISMAEL FATIMA AMARAL",
    "payer_document_number": "10003550206",
    "payer_person_type": "natural",
    "target_name": "TESTE LTDA.",
    "target_trading_name": null,
    "address": "Rua Tapajos, 941",
    "state": "RJ"
  }
}

STATUS

200

Response Body: 动态 QR Code — 带到期日

{
  "qr_code_type": "dynamic_term",
  "qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc123456000053039865802BR5925Oncred Sociedade de Credi6015TESTE 62070503***6304D008",
  "pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
  "receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
  "amount": "55.59",
  "status": "ATIVA",
  "qr_code_data": {
    "target_pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
    "receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
    "original_amount": "55.59",
    "reduction_amount": null,
    "discount_amount": null,
    "fee_amount": null,
    "fine_amount": null,
    "amount": "55.59",
    "due_date": "2023-03-27",
    "days_after_due_accepted": 16,
    "created_at": "2023-01-10T19:49:58.30Z",
    "presented_at": "2023-03-10T15:32:15.87Z",
    "question_to_payer": null,
    "status": "ATIVA",
    "revision": 0,
    "category_code": "0000",
    "reusable_qrcode": "no",
    "receiver_url": "invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae351234",
    "additional_data": [],
    "payer_name": "Willian Rocha",
    "payer_document_number": "00000000000",
    "payer_person_type": "natural",
    "target_name": "TESTE LTDA.",
    "target_trading_name": null,
    "address": "Rua Tapajos, 941",
    "state": "SP",
    "city": "Sao Caetano do Sul",
    "postal_code": "09551230"
  }
}

响应字段

字段	类型	描述	存在于
`qr_code_type`	string	QR Code 类型：`static`、`dynamic_instant` 或 `dynamic_term`	所有
`qr_code_payload`	string	请求中发送的原始 EMV payload	所有
`qr_code_data.target_pix_key`	string	收款人 Pix 密钥	所有
`qr_code_data.amount`	string/decimal	账单金额。`dynamic_term` 表示罚息/利息/折扣后的最终金额	所有
`qr_code_data.receiver_conciliation_id`	string	收款人对账标识符（txid）	所有
`qr_code_data.additional_data`	array	附加信息列表 `{name, value}`	所有
`qr_code_data.category_code`	string	商户类别代码（MCC）	所有
`qr_code_data.city`	string	收款人所在城市	所有
`qr_code_data.postal_code`	string	收款人邮政编码	所有
`qr_code_data.reusable_qrcode`	string	`yes` 表示 QR Code 可多次支付，`no` 表示不可	所有
`qr_code_data.receiver_url`	string	收款人 PSP 的 URL（BR Code 的 `loc` 字段）	`dynamic_*`
`qr_code_data.status`	string	账单状态（见下方枚举值）	`dynamic_*`
`qr_code_data.revision`	integer	账单当前版本号	`dynamic_*`
`qr_code_data.created_at`	string (ISO)	收款人 PSP 上账单的创建时间	`dynamic_*`
`qr_code_data.presented_at`	string (ISO)	账单向付款人展示的时间	`dynamic_*`
`qr_code_data.question_to_payer`	string	收款人对付款人的留言（`solicitacaoPagador`）	`dynamic_*`
`qr_code_data.payer_name`	string	收款人指定的预期付款人姓名	`dynamic_*`
`qr_code_data.payer_document_number`	string	预期付款人 CPF/CNPJ	`dynamic_*`
`qr_code_data.payer_person_type`	string	`natural` 或 `legal`	`dynamic_*`
`qr_code_data.target_name`	string	收款人姓名	`dynamic_*`
`qr_code_data.expiration_seconds`	integer	账单有效期（秒），从 `created_at` 起算	`dynamic_instant`
`qr_code_data.can_change`	string	`yes` 表示付款人可修改金额，`no` 表示不可	`dynamic_instant`
`qr_code_data.original_amount`	string/decimal	罚息/利息/折扣前的原始账单金额	`dynamic_term`
`qr_code_data.due_date`	string (date)	账单到期日	`dynamic_term`
`qr_code_data.days_after_due_accepted`	integer	到期后仍可接受付款的天数	`dynamic_term`
`qr_code_data.fine_amount`	string/decimal	到期后产生的罚款	`dynamic_term`
`qr_code_data.fee_amount`	string/decimal	到期后产生的利息	`dynamic_term`
`qr_code_data.discount_amount`	string/decimal	到期前的折扣	`dynamic_term`
`qr_code_data.reduction_amount`	string/decimal	账单减免金额	`dynamic_term`
`qr_code_data.target_trading_name`	string	收款人商户名	`dynamic_*`
`qr_code_data.address`	string	收款人街道地址	`dynamic_*`
`qr_code_data.state`	string	收款人所在州	`dynamic_*`

响应根级别的已弃用字段

以下字段仅为向后兼容而在响应根级别返回，将在未来版本中移除。请使用 qr_code_data 中的对应字段。

字段	对应字段	存在于
`pix_key`	`qr_code_data.target_pix_key`	所有
`transfer_amount`	`qr_code_data.amount`	`static`
`additional_data`	`qr_code_data.additional_data`	`static`
`amount`	`qr_code_data.amount`	`dynamic_*`
`receiver_conciliation_id`	`qr_code_data.receiver_conciliation_id`	`dynamic_*`
`status`	`qr_code_data.status`	`dynamic_*`

静态 QR Code

按 BR Code 规范，静态 QR Code 不包含预期付款人数据、到期日、罚款、利息、折扣或减免。这些字段仅存在于动态 QR Code 中。

状态

对于动态 QR Code 类型，将根据以下枚举表返回 QR Code 状态。

动态 QR Code 状态枚举值

枚举值	描述
ATIVA	账单可用，尚未付款
CONCLUIDA	账单已付款并结束
REMOVIDA_PELO_USUARIO_RECEBEDOR	收款方用户申请移除账单
REMOVIDA_PELO_PSP	收款银行申请移除账单

错误

STATUS

400

QR Code 格式无效

{
  "data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}

未在 payload 中识别到 QR Code 类型

{
  "data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}

处理动态 QR Code 时出错

{
  "data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}

Request​

Body 参数​

Response​

响应字段​

动态 QR Code 状态枚举值​

错误​

Request

Body 参数

Response

响应字段

动态 QR Code 状态枚举值

错误