Decodificação de QR Code estáticos e dinâmicos
stable
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://api-mtls.sandbox.bankly.com.br/pix/qrcodes/decode \
--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 | Especificaçã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. | Informe somente 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 | 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 ("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 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.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.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 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 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, que pode ser "STORE" ou "OTHER_BUSINESSES". |
withdrawalDetail.providerIspb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco 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, que pode ser "STORE" ou "OTHER_BUSINESSES". |
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
econciliationId
retornados nesta API. OconciliationId
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 Floresta",
"document": {
"value": "34183937000161",
"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": "Editora Floresta",
"document": {
"value": "34183937000161",
"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": "Santarém"
},
"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": "Editora FLoresta",
"document": {
"value": "34183937000161",
"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": "Santarém"
},
"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": "Nísia Floresta",
"document": {
"value": "47742663023",
"type": "CPF"
}
},
"holder": {
"type": "BUSINESS",
"name": "Editora Floresta",
"document": {
"value": "34183937000161",
"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": "Santarém"
},
"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": "Nísia floresta",
"document": {
"value": "47742663023",
"type": "CPF"
}
},
"holder": {
"type": "BUSINESS",
"name": "Editora Floresta",
"document": {
"value": "34183937000161",
"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": "Santarém"
},
"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": "Editora Floresta",
"document": {
"value": "34183937000161",
"type": "CNPJ"
}
},
"holder": {
"type": "CUSTOMER",
"name": "Nísia Floresta",
"tradingName": "QR Codes Pix",
"document": {
"value": "47742663023",
"type": "CPF"
}
},
"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 | The QrCodePayload is invalid or cannot be decoded. Check it out with the PSP. | 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 | 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 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. 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.
Updated 24 days ago