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

stable

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: {{correlationId}}' \ 
--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:

ScopeDescrição
pix.qrcode.readConcede acesso para decodificar um QR Code.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-correlation-idObrigatório. Informe um GUID, sendo um novo cada requisição.
x-bkly-pix-user-idObrigatório. Número do documento do usuário que está fazendo a requisição. Insira apenas números, sem formataçã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:

NomeTipoDescrição
encodedValuestringObrigató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:

NomeTipoDescrição
endToEndIdstringIdentificador único gerado pelo Bacen que deve ser informado ao realizar o pagamento do QR Code.
conciliationId stringID de conciliação, o qual pode ser utilizado para conciliação dos pagamentos.
addressingKeyobjectObjeto que contém informações sobre a chave de endereçamento DICT.
addressingKey.typestringTipo de chave de endereçamento DICT. Exemplo: CPF, CNPJ, EMAIL, PHONE ou EVP.
addressingKey.valuestringValor da chave escolhida.
qrCodeTypestringInforma se o QR Code é estático (STATIC) ou dinâmico (DYNAMIC).
payerobjectObjeto 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.typestringTipo de pagador, o qual pode ser "CUSTOMER" ou "BUSINESS".
payer.namestringNome do pagador.
payer.documentobjectObjeto que contém informações sobre o documento do pagador.
payer.document.valuestringNúmero do documento.
payer.document.typestringTipo do documento, o qual pode ser "CPF ou "CNPJ".
holderobjectObjeto que contém informações sobre o titular da conta a ser utilizada no pagamento.
holder.typestringTipo de titular, o qual pode ser "CUSTOMER" ou "BUSINESS".
holder.namestringNome do titular.
holder.documentobjectObjeto que contém informações sobre o documento do titular.
holder.document.valuestringNúmero do documento.
holder.document.typestringTipo do documento, o qual pode ser "CPF ou "CNPJ".
bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
bank.namestringNome do banco. Este campo retorna apenas em caso de leitura de QR Code estático.
bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. Este campo retorna apenas em caso de leitura de QR Code dinâmico.
paymentobjectObjeto que contém informações sobre o pagamento a ser realizado.
payment.baseValuenumberValor de base.
payment.interestValuenumberValor de juros.
payment.penaltyValuenumberValor de multa.
payment.discountValuenumberValor do desconto.
payment.reductionValuenumberValor do abatimento.
payment.totalValuenumberIndica o valor do total da compra ou transferência.
payment.dueDatestringData de vencimento do pagamento, no formato YYYY-MM-DDTHH:mm:SS.MMMZ.
payment.changeValuenumberIndica o valor do troco em espécie. Este campo somente é retornado em caso de decodificação de QR Code para Pix Troco.
payment.withdrawalValuenumberIndica o valor do saque em espécie. Este campo somente é retornado em caso de decodificação de QR Code para Pix Saque.
locationobjectObjeto que contém informações sobre a localidade do recebedor do pagamento.
location.citystringNome da cidade do recebedor do pagamento.
location.zipCodestringCódigo postal do recebedor do pagamento. Este campo retorna apenas na leitura de QR Codes estáticos.
withdrawalDetailobjectObjeto que contém informações referentes à decodificação de QR Code para Pix Saque.
withdrawalDetail.changeAmountTypestringIndica 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.agentTypestringEspecifica o tipo de estabelecimento comercial que está fornecendo o saque, o qual pode ser STORE ou OTHER_BUSINESSES.
withdrawalDetail.providerIspbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do provedor.
changeAmountDetailobjectObjeto que contém informações referentes à decodificação de QR Code para Pix Troco.
changeAmountDetail.changeAmountTypestringIndica 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.agentTypestringEspecifica o tipo de estabelecimento comercial que está fornecendo o troco, o qual pode ser STORE ou OTHER_BUSINESSES.
qrCodePurposestringRazã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 CodeCódigoDescrição
400QRCODE_CANNOT_BE_DECODEDO QR Code não pode ser decodificado.
400INVALID_USER_IDVerifique se o cabeçalho x-bkly-pix-user-id apresenta um CPF ou CNPJ válido.
400QRCODE_PAYLOAD_LOCATION_REMOVEDO QR Code não está mais disponível para leitura por ter sido removido pela PSP do recebedor.
400REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIODNão está disponível fora do horário comercial.
400ENTRY_NOT_FOUNDA chave que está sendo usada para gerar o QR Code não existe.
400CASHOUT_LIMIT_NOT_ENOUGHA transação excede o limite de valor da transferência.
408REQUEST_TIMEOUTA requisição excedeu o tempo limite da solicitação.
422INVALID_QRCODE_PAYLOAD_CONTENT_TO_DECODEO qrcodePayload informado tem conteúdo inválido para ser decodificado. Certifique-se de que o PSP recebedor está gerando um qrcodePayload válido.

Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.