Decodificação de QR Code estáticos e dinâmicos

O endpoint de decodificação do Bankly está preparada 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

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/decode \

--curl--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/decode' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'api-version: 1.0' \ 
--header 'x-bkly-pix-user-id: {{clientDocument}}' \ 
--header 'x-correlation-id: {{GUID}}' \ 
--header 'Authorization: Bearer {{accessToken}}'  \ 
--data-raw '{ 
    "encodedValue": {{yourEncode}} 
}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`pix.qrcode.read`	Concede acesso para decodificar um QR Code.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`x-bkly-pix-user-id`	Obrigatório. Número do documento do usuário que está fazendo a requisição. Insira apenas números, sem formatação.
`x-correlation-id`	Se desejar, informe um GUID v4, sendo um novo cada requisição.

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
`encodedValue`	`string`	Obrigatório. Conteúdo do QR Code em base64.

{ 
    "encodedValue": {{yourEncode}} 
}

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`	ID de conciliação, o qual pode ser utilizado para conciliação dos pagamentos.
`addressingKey`	`object`	Objeto que contém informações sobre a chave de endereçamento DICT.
`addressingKey.type`	`string`	Tipo de chave de endereçamento DICT. Exemplo: CPF, CNPJ, EMAIL, PHONE ou EVP.
`addressingKey.value`	`string`	Valor da chave escolhida.
`qrCodeType`	`string`	Informa se o QR Code é estático (STATIC) ou dinâmico (DYNAMIC).
`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 pagador, o qual pode ser "CUSTOMER" ou "BUSINESS".
`payer.name`	`string`	Nome do pagador.
`payer.document`	`object`	Objeto que contém informações sobre o documento do pagador.
`payer.document.value`	`string`	Número do documento.
`payer.document.type`	`string`	Tipo do documento, o qual pode ser "CPF ou "CNPJ".
`holder`	`object`	Objeto que contém informações sobre o titular da conta a ser utilizada no pagamento.
`holder.type`	`string`	Tipo de titular, o qual pode ser "CUSTOMER" ou "BUSINESS".
`holder.name`	`string`	Nome do titular.
`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 do documento, o qual pode ser "CPF ou "CNPJ".
`bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`bank.name`	`string`	Nome do banco. Este campo retorna apenas em caso de leitura de QR Code estático.
`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.
`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.
`location`	`object`	Objeto que contém informações sobre a localidade do recebedor do pagamento.
`location.city`	`string`	Nome da cidade do recebedor do pagamento.
`location.zipCode`	`string`	Código postal do recebedor do pagamento. Este campo retorna apenas na leitura de QR Codes estáticos.
`withdrawalDetail`	`object`	Objeto que contém informações referentes à decodificação de QR Code para Pix Saque.
`withdrawalDetail.changeAmountType`	`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.
`withdrawalDetail.agentType`	`string`	Especifica o tipo de estabelecimento comercial que está fornecendo o saque, o qual pode ser STORE ou OTHER_BUSINESSES.
`withdrawalDetail.providerIspb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do provedor.
`changeAmountDetail`	`object`	Objeto que contém informações referentes à decodificação de QR Code para Pix Troco.
`changeAmountDetail.changeAmountType`	`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.
`changeAmountDetail.agentType`	`string`	Especifica o tipo de estabelecimento comercial que está fornecendo o troco, o qual pode ser STORE ou OTHER_BUSINESSES.
`qrCodePurpose`	`string`	Razão da emissão do QR Code, a qual pode ser: PURCHASE_OR_TRANSFER (compra ou transferência), CHANGE (para Pix Troco) e 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": "E131400882021210234719976289315",
    "conciliationId": "12345",
    "addressingKey": {
        "type": "EVP",
        "value": "721f7f5-9227-411b-9297-c5ded2e7diii"
    },
    "qrCodeType": "STATIC",
    "holder": {
        "type": "BUSINESS",
        "name": "Editora Nísia Floresta",
        "document": {
            "value": "***426630**",
            "type": "CNPJ"
        }
    },
    "bank": {
        "name": "Acesso Soluções De Pagamento S.A."
    },
    "payment": {
        "baseValue": 0.0,
        "interestValue": 0.0,
        "penaltyValue": 0.0,
        "discountValue": 0.0,
      	"reductionValue": 0.0,
        "totalValue": 1.00,
        "dueDate": "2023-03-31T17:55:24.311Z",
        "changeValue": 0.0,
        "withdrawalValue": 0.0
    },
    "location": {
        "city": "Santarém",
        "zipCode": "68060100"
    },
    "qrCodePurpose": "PURCHASE_OR_TRANSFER"
}

{
    "endToEndId": "E1314008820231114172019088054345",
    "conciliationId": "2279e2a1a6e446b18cecf13f0",
    "addressingKey": {
        "type": "EVP",
        "value": "4004901d-bd85-4769-8e52-cb4c42c506dc"
    },
    "qrCodeType": "STATIC",
    "holder": {
        "type": "BUSINESS",
        "name": "QRTester",
        "document": {
            "value": "11111111000191",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "99999008"
    },
    "payment": {
        "baseValue": 0.0,
        "interestValue": 0.0,
        "penaltyValue": 0.0,
        "discountValue": 0.0,
        "totalValue": 408.07,
        "dueDate": "0001-01-01T00:00:00",
        "changeValue": 0.0,
        "withdrawalValue": 408.07,
        "isSinglePayment": false,
        "qrCodeChangeAmountType": "NOT_ALLOWED"
    },
    "location": {
        "city": "BRASILIA"
    },
    "additionalData": [
        {
            "name": "",
            "value": "Jornada pagador 20151"
        }
    ],
    "withdrawalDetail": {
        "changeAmountType": "NOT_ALLOWED",
        "agentType": "STORE",
        "providerIspb": "99999008"
    },
    "qrCodePurpose": "WITHDRAWAL"
}

{
    "endToEndId": "E1314008820211210235032867394226",
    "conciliationId": "af7a357fe37b40be88a83f0f04650638",
    "addressingKey": {
        "type": "EVP",
        "value": "4004901d-bd85-4769-8e52-cb4c42c506dc"
    },
    "qrCodeType": "DYNAMIC",
    "payer": {
        "type": "CUSTOMER",
        "name": "Peter Parker",
        "document": {
            "value": "***111110001**",
            "type": "CNPJ"
        }
    },
    "holder": {
        "type": "BUSINESS",
        "name": "Company name",
        "document": {
            "value": "***111110001**",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "99999008"
    },
    "payment": {
        "baseValue": 957.39,
        "interestValue": 0.0,
        "penaltyValue": 0.0,
        "discountValue": 0.0,
      	"reductionValue": 0.0,
        "totalValue": 957.39,
        "dueDate": "0001-01-01T00:00:00",
        "changeValue": 0.0,
        "withdrawalValue": 0.0
    },
    "location": {
        "city": "BRASILIA"
    },
    "additionalData": [
        {
            "name": "Entrega",
            "value": "Residencial"
        }
    ],
    "qrCodePurpose": "PURCHASE_OR_TRANSFER"
}

{
    "endToEndId": "E1314008820231114171927102983378",
    "conciliationId": "361b0473f5714e3dbba1a48ceb26e9a0",
    "addressingKey": {
        "type": "EVP",
        "value": "4004901d-bd85-4769-8e52-cb4c42c506dc"
    },
    "qrCodeType": "DYNAMIC",
    "payer": {
        "type": "CUSTOMER",
        "name": "Fulano de Tal",
        "document": {
            "value": "***633284**",
            "type": "CPF"
        }
    },
    "holder": {
        "type": "BUSINESS",
        "name": "QRTester",
        "document": {
            "value": "11111111000191",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "99999008"
    },
    "payment": {
        "baseValue": 0.00,
        "interestValue": 0.0,
        "penaltyValue": 0.0,
        "discountValue": 0.0,
        "totalValue": 283.94,
        "dueDate": "2021-11-09T21:43:51.842Z",
        "changeValue": 0.0,
        "withdrawalValue": 283.94,
        "isSinglePayment": false,
        "qrCodeChangeAmountType": "NOT_ALLOWED"
    },
    "location": {
        "city": "BRASILIA"
    },
    "additionalData": [
        {
            "name": "Entrega",
            "value": "Residencial"
        }
    ],
    "withdrawalDetail": {
        "changeAmountType": "NOT_ALLOWED",
        "agentType": "WITHDRAWAL_PROVIDER",
        "providerIspb": "99999008"
    },
    "qrCodePurpose": "WITHDRAWAL"
}

{
    "endToEndId": "E1314008820231114172109516637904",
    "conciliationId": "00775d7611e94305920392ae1ccff480",
    "addressingKey": {
        "type": "EVP",
        "value": "4004901d-bd85-4769-8e52-cb4c42c506dc"
    },
    "qrCodeType": "DYNAMIC",
    "payer": {
        "type": "CUSTOMER",
        "name": "Fulano de Tal",
        "document": {
            "value": "***105481**",
            "type": "CPF"
        }
    },
    "holder": {
        "type": "BUSINESS",
        "name": "QRTester",
        "document": {
            "value": "11111111000191",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "99999008"
    },
    "payment": {
        "baseValue": 839.01,
        "interestValue": 0.0,
        "penaltyValue": 0.0,
        "discountValue": 0.0,
        "totalValue": 1773.88,
        "dueDate": "2021-11-09T21:43:52.156Z",
        "changeValue": 934.87,
        "withdrawalValue": 0.0,
        "isSinglePayment": false,
        "qrCodeChangeAmountType": "NOT_ALLOWED"
    },
    "location": {
        "city": "BRASILIA"
    },
    "additionalData": [
        {
            "name": "Entrega",
            "value": "Residencial"
        }
    ],
    "changeAmountDetail": {
        "changeAmountType": "NOT_ALLOWED",
        "agentType": "STORE",
        "providerIspb": "99999008"
    },
    "qrCodePurpose": "CHANGE_AMOUNT"
}

{
    "endToEndId": "E1314008820211210235723815730157",
    "conciliationId": "c4164f64f8f849cb80b5b01cf9a31b85",
    "addressingKey": {
        "type": "EVP",
        "value": "4004901d-bd85-4769-8e52-cb4c42c506dc"
    },
    "qrCodeType": "DYNAMIC",
    "payer": {
        "type": "CUSTOMER",
        "name": "Peter Parker",
        "document": {
            "value": "***111110001**",
            "type": "CNPJ"
        }
    },
    "holder": {
        "type": "BUSINESS",
        "name": "Company Name",
        "tradingName": "QR Codes Pix",
        "document": {
            "value": "***111110001**",
            "type": "CNPJ"
        }
    },
    "bank": {
        "ispb": "99999008"
    },
    "payment": {
        "baseValue": 110.71,
        "interestValue": 20.00,
        "penaltyValue": 5.00,
        "discountValue": 0.0,
      	"reductionValue": 0.0,
        "totalValue": 135.71,
        "dueDate": "2021-11-30T00:00:00",
        "changeValue": 0.0,
        "withdrawalValue": 0.0
    },
    "additionalData": [
        {
            "name": "Multa por valor fixo",
            "value": "5.00"
        },
        {
            "name": "Juros absolutos por dias corridos",
            "value": "2.00"
        }
    ],
    "qrCodePurpose": "PURCHASE_OR_TRANSFER"
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

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	—	O QR Code não pode ser decodificado.
400	INVALID_USER_ID	Ensure that the x-bkly-pix-user-id header is a valid CPF or CNPJ document.	Verifique se o cabeçalho `x-bkly-pix-user-id` apresenta um CPF ou CNPJ válido.
400	QRCODE_PAYLOAD_LOCATION_REMOVED	—	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 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	—	A requisição excedeu o tempo limite da solicitação.
422	INVALID_QRCODE_PAYLOAD_CONTENT_TO_DECODE	—	O `qrcodePayload` informado tem conteúdo inválido para ser decodificado. Certifique-se de que o PSP recebedor está gerando um `qrcodePayload` válido.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.

Decodificação de QR Code estáticos e dinâmicos

📘
Nota

🚧
Importante

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Resposta (Response)

🚧
Importante

👍
Dica

Erros

Eventos

📘Nota

🚧Importante

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Resposta (Response)

🚧Importante

👍Dica

Erros

Eventos

📘
Nota

🚧
Importante

🚧
Importante

👍
Dica