Pular para o conteúdo principal

Decodificar QR Code Pix

Decodifica um QR Code Pix retornando os dados contidos no payload. Não realiza consulta DICT na conta destino e não persiste o QR Code consultado — adequado para fluxos de pré-visualização (preview) antes da decisão de pagamento.

Request​

ENDPOINT
/pix/decode_qrcode_payload
MÉTODO
POST
Request Body
{
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD"
}

Body Params​

CampoTipoDescriçãoCaracteres
qr_code_payload *stringPix Copia e Cola-

Response​

STATUS
200
Response Body: QR Code estático
{
  "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 dinâmico pagamento imediato
{
  "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 dinâmico com vencimento
{
  "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"
  }
}

Campos da resposta​

CampoTipoDescriçãoPresente em
qr_code_typestringTipo do QR Code: static, dynamic_instant ou dynamic_termTodos
qr_code_payloadstringPayload EMV original enviado na requisiçãoTodos
qr_code_data.target_pix_keystringChave Pix do recebedorTodos
qr_code_data.amountstring/decimalValor da cobrança. Em dynamic_term representa o valor final (após multa/juros/desconto)Todos
qr_code_data.receiver_conciliation_idstringIdentificador de conciliação do recebedor (txid)Todos
qr_code_data.additional_dataarrayLista de informações adicionais {name, value}Todos
qr_code_data.category_codestringCódigo de categoria do estabelecimento (MCC)Todos
qr_code_data.citystringCidade do recebedorTodos
qr_code_data.postal_codestringCEP do recebedorTodos
qr_code_data.reusable_qrcodestringyes se o QR Code pode ser pago múltiplas vezes, no caso contrárioTodos
qr_code_data.receiver_urlstringURL do PSP do recebedor (campo loc do BR Code)dynamic_*
qr_code_data.statusstringStatus da cobrança (ver enumeradores abaixo)dynamic_*
qr_code_data.revisionintegerVersão atual da cobrançadynamic_*
qr_code_data.created_atstring (ISO)Data de criação da cobrança no PSP do recebedordynamic_*
qr_code_data.presented_atstring (ISO)Data de apresentação da cobrança ao pagadordynamic_*
qr_code_data.question_to_payerstringMensagem do recebedor para o pagador (solicitacaoPagador)dynamic_*
qr_code_data.payer_namestringNome do pagador esperado, quando informado pelo recebedordynamic_*
qr_code_data.payer_document_numberstringCPF/CNPJ do pagador esperadodynamic_*
qr_code_data.payer_person_typestringnatural ou legaldynamic_*
qr_code_data.target_namestringNome do recebedordynamic_*
qr_code_data.expiration_secondsintegerTempo de validade da cobrança em segundos a partir de created_atdynamic_instant
qr_code_data.can_changestringyes se o pagador pode alterar o valor, no caso contráriodynamic_instant
qr_code_data.original_amountstring/decimalValor original da cobrança antes de multa/juros/descontodynamic_term
qr_code_data.due_datestring (date)Data de vencimento da cobrançadynamic_term
qr_code_data.days_after_due_acceptedintegerDias após o vencimento em que a cobrança ainda aceita pagamentodynamic_term
qr_code_data.fine_amountstring/decimalMulta aplicada após o vencimentodynamic_term
qr_code_data.fee_amountstring/decimalJuros aplicados após o vencimentodynamic_term
qr_code_data.discount_amountstring/decimalDesconto concedido antes do vencimentodynamic_term
qr_code_data.reduction_amountstring/decimalAbatimento aplicado à cobrançadynamic_term
qr_code_data.target_trading_namestringNome fantasia do recebedordynamic_*
qr_code_data.addressstringLogradouro do recebedordynamic_*
qr_code_data.statestringUF do recebedordynamic_*
Campos deprecated na raiz da resposta

Os campos abaixo são retornados na raiz da resposta apenas por retrocompatibilidade e serão removidos em uma versão futura. Utilize os equivalentes dentro de qr_code_data.

CampoEquivalentePresente em
pix_keyqr_code_data.target_pix_keyTodos
transfer_amountqr_code_data.amountstatic
additional_dataqr_code_data.additional_datastatic
amountqr_code_data.amountdynamic_*
receiver_conciliation_idqr_code_data.receiver_conciliation_iddynamic_*
statusqr_code_data.statusdynamic_*
QR Code estático

Por especificação do BR Code, QR Codes estáticos não contêm dados do pagador esperado, data de expiração, multa, juros, descontos nem abatimento. Esses campos só existem em QR Codes dinâmicos.

Status

Para o QR Code do tipo dinâmico, é retornado o status do QR Code conforme a tabela de enumeradores abaixo.

Enumeradores Status QR Code dinâmico​

EnumeradorDescrição
ATIVACobrança disponível, sem pagamento realizado
CONCLUIDACobrança paga e finalizada
REMOVIDA_PELO_USUARIO_RECEBEDORUsuário recebedor solicitou a remoção da cobrança
REMOVIDA_PELO_PSPBanco recebedor solicitou a remoção da cobrança

Erros​

STATUS
400
QR Code com formato inválido
{
  "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\"}"
}

Tipo de QR Code não identificado no payload
{
  "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\"}"
}

Erro ao processar QR Code dinâmico
{
  "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\"}"
}