Decodificação de QR Codes

O endpoint de decodificação do Bankly está preparado para ler QR Codes estáticos e dinâmicos gerados por qualquer instituição financeira.

📘
Nota
Os QR Codes dinâmicos podem destinar-se a pagamentos imediatos e futuros (com vencimento).

Ao decodificar um QR Code Pix, você obterá:

O endToEndId, um identificador único gerado pelo Bacen que deve ser informado ao realizar o pagamento do QR Code;
A chave Pix;
O valor do pagamento, caso ele tenha sido adicionado em na geração do QR Code. No Bankly, o valor poderá ser alterado pelo pagador no momento de efetuar da transação.

⚠️
Importante
Para fazer a leitura de um QR Code de pagamento, obrigatoriamente, o conteúdo deve ser enviado em base64.

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/pix/qrCode/decode

--request POST 'https://sandbox.hiperbanco.com.br/pix/qrCode/decode' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "code": "{{yourEncode}}"
}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
version	cutting-edge	Essa propriedade garante que o response da API seja retornado no formato JSON
Authorization	Bearer token	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie o seguinte campo em formato JSON:

Nome	Tipo	Descrição
`code`	`string`	Obrigatório. Conteúdo do QR Code em base64.
`cityCode`	`string`	Obrigatório. Código de município do usuário pagador no IBGE.

{
  "code": "{{encodedValue}}",
  "cityCode": "3550308"
}

Resposta (Response)

Os status code 200 indica que a solicitação foi aceita e que a decodificação do QR Code foi realizada com sucesso.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
endToEndId	string	Identificador único gerado pelo Bacen que deve ser informado ao realizar o pagamento do QR Code.
conciliationId	string	Identificador utilizado para conciliação dos pagamentos. Importante: este campo somente será retornado caso ele tenha sido enviado no momento da emissão do QR Code.
addressingKey	object	Objeto que contém informações sobre a chave de endereçamento.
addressingKey.type	string	Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE", "EMAIL" ou "EVP".
addressingKey.value	string	Valor da chave.
qrCodeType	string	Informa se o QR Code é estático ("staticQrCode") ou dinâmico ("dynamicQrCode").
payer	object	Objeto que contém informações sobre o pagador da transação. Este campo retorna apenas em caso de leitura de QR Code dinâmico.
payer.type	string	Tipo de cliente pagador, que pode ser "CUSTOMER" ou "BUSINESS".
payer.name	string	Nome do pagador da transação.
payer.document	object	Objeto que contém informações sobre o documento do pagador da transação.
payer.document.value	string	Número do documento.
payer.document.type	string	Tipo do documento do pagador da transação, que pode ser "CPF" ou "CNPJ".
holder	object	Objeto que contém informações sobre o titular da conta a ser utilizada na transação.
holder.type	string	Tipo de titular, que pode ser "CUSTOMER" ou "BUSINESS".
holder.name	string	Nome do titular.
holder.tradingName	string	Nome fantasia (nome comercial) do titular. (Em caso do holder ser BUSINESS)
holder.document	object	Objeto que contém informações sobre o documento do titular.
holder.document.value	string	Número do documento.
holder.document.type	string	Tipo de documento do titular da conta, que pode ser "CPF" ou "CNPJ".
bank	object	Objeto que contém informações sobre o banco ao qual a conta pertence.
bank.ispb	string	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. Este campo retorna apenas em caso de leitura de QR Code dinâmico.
bank.name	string	Nome do banco. Este campo retorna apenas em caso de leitura de QR Code estático.
payment	object	Objeto que contém informações sobre o pagamento a ser realizado.
payment.baseValue	number	Valor de base.
payment.interestValue	number	Valor de juros.
payment.penaltyValue	number	Valor de multa.
payment.discountValue	number	Valor do desconto.
payment.reductionValue	number	Valor do abatimento.
payment.totalValue	number	Indica o valor do total da compra ou transferência.
payment.dueDate	string	Data de vencimento do pagamento, no formato ISO 8601 - UTC.
payment.changeValue	number	Indica o valor do troco em espécie. Este campo somente é retornado em caso de decodificação de QR Code para Pix Troco.
payment.withdrawalValue	number	Indica o valor do saque em espécie. Este campo somente é retornado em caso de decodificação de QR Code para Pix Saque. Caso não seja Pix Saque, este valor será 0
payment.isSinglePayment	boolean	Indica se o pagamento é único (true) ou pode ser parcelado (false).
payment.qrCodeChangeAmountType	string	Indica a possibilidade de alteração do valor do QR Code. Se esse campo retornar "ALLOWED", será permitido alterar o valor. Caso o retorno seja "NOT_ALLOWED", não será permitido realizar a alteração do valor trazido pelo QR Code.
location	object	Objeto que contém informações sobre a localidade do recebedor da transação.
location.city	string	Nome da cidade do recebedor da transação.
location.zipCode	string	Código postal do recebedor da transação. Este campo retorna apenas na leitura de QR Codes dinâmicos.
qrCodePurpose	string	Razão da emissão do QR Code, que pode ser "PURCHASE_OR_TRANSFER" (compra ou transferência), "CHANGE" (para Pix Troco) ou "WITHDRAWAL" (para Pix Saque).

⚠️
Importante
Para fazer um pagamento Pix por QR Code, você precisará repassar os valores dos campos endToEndId e conciliationId retornados nesta API. O conciliationId será requerido para pagamento de QR Code dinâmico.

{
    "endToEndId": "E123456782025071601239C9876E0FF8",
    "conciliationId": "X9YTuvDgwaBbYzK78zd8n9eyHmmrf",
    "addressingKey": {
        "type": "EVP",
        "value": "a123bcd4-5678-9123-4567-8e9f0a1b2c3d"
    },
    "qrCodeType": "dynamicQrCode",
    "payer": {
        "type": "CUSTOMER",
        "name": "Editora Floresta",
        "document": {
            "value": "34183937000161",
            "type": "CNPJ"
        }
    },
    "holder": {
        "type": "BUSINESS",
        "name": "98765432 Tech Solutions Ltda",
        "tradingName": "98765432 Tech Solutions",
        "document": {
            "value": "98765432000121",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "12345678",
        "name": "Fintech Pagamentos S.A. - Instituição De Pagamento"
    },
    "payment": {
        "baseValue": 1250.50,
        "interestValue": 25.75,
        "penaltyValue": 10.00,
        "discountValue": 50.25,
        "reductionValue": 0,
        "totalValue": 1236.00,
        "dueDate": "2025-11-15T14:30:00.000",
        "changeValue": 0,
        "withdrawalValue": 0,
        "isSinglePayment": true,
        "qrCodeChangeAmountType": "NOT_ALLOWED"
    },
    "location": {
        "city": "São Paulo",
        "zipCode": "01311000"
    },
    "qrCodePurpose": "PURCHASE_OR_TRANSFER"
}

{
    "endToEndId": "E00000000202507152359XYZ12345678",
    "conciliationId": "a1b2c3d4EfGhIjKlMnOpQrStUv",
    "addressingKey": {
        "type": "EVP",
        "value": "12345678-abcd-1234-efgh-56789abcdef0"
    },
    "qrCodeType": "staticQrCode",
    "holder": {
        "type": "BUSINESS",
        "name": "Empresa Fictícia Ltda",
        "tradingName": "EmpFictícia",
        "document": {
            "value": "12345678000199",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "00000000",
        "name": "Banco de Testes S.A. - Instituição de Pagamento"
    },
    "payment": {
        "baseValue": 150.75,
        "interestValue": 0,
        "penaltyValue": 0,
        "discountValue": 10.75,
        "reductionValue": 0,
        "totalValue": 140.00,
        "changeValue": 0,
        "withdrawalValue": 0,
        "isSinglePayment": true,
        "qrCodeChangeAmountType": "NOT_ALLOWED"
    },
    "location": {
        "city": "Cidade Teste",
        "zipCode": "00000-000"
    },
    "additionalData": [
        {
        }
    ],
    "qrCodePurpose": "PURCHASE_OR_TRANSFER"
}

Erros

Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
400	QRCODE_CANNOT_BE_DECODED	The QrCodePayload is invalid or cannot be decoded. Check it out with the PSP.	O QR Code não pode ser decodificado.
400	QRCODE_PAYLOAD_LOCATION_REMOVED	The QrCodePayload location was removed by PSP.	O QR Code não está mais disponível para leitura por ter sido removido pela PSP do recebedor.
400	REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIOD	Request not allowed out of business period.	Não está disponível fora do horário comercial.
400	ENTRY_NOT_FOUND	Entry not found.	A chave que está sendo usada para gerar o QR Code não existe.
400	CASHOUT_LIMIT_NOT_ENOUGH	Sender does not have sufficient cash out limit.	A transação excede o limite de valor da transferência.
408	REQUEST_TIMEOUT	Transaction exceeded request limit timeout.	A requisição excedeu o tempo limite da solicitação.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.