Manual do Dev
InstitucionalBlogService DeskStatus Page

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

stable

Suggest Edits

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:

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

Cabeçalhos (Headers)

NomeDescriçãoEspecificaçã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-bkly-pix-user-idObrigatório. Número do documento do usuário que está fazendo a requisição.Informe somente números, sem formatação.
x-correlation-idSe 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:

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 stringIdentificador 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.
addressingKeyobjectObjeto que contém informações sobre a chave de endereçamento.
addressingKey.typestringTipo de chave, que pode ser "CPF", "CNPJ", "PHONE", "EMAIL" ou "EVP".
addressingKey.valuestringValor da chave.
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 cliente pagador, que pode ser "CUSTOMER" ou "BUSINESS".
payer.namestringNome do pagador da transação.
payer.documentobjectObjeto que contém informações sobre o documento do pagador da transação.
payer.document.valuestringNúmero do documento.
payer.document.typestringTipo do documento do pagador da transação, que pode ser "CPF" ou "CNPJ".
holderobjectObjeto que contém informações sobre o titular da conta a ser utilizada na transação.
holder.typestringTipo de titular, que 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 de documento do titular da conta, que 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 ISO 8601 - UTC.
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 da transação.
location.citystringNome da cidade do recebedor da transação.
location.zipCodestringCódigo postal do recebedor da transação. 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, que pode ser "STORE" ou "OTHER_BUSINESSES".
withdrawalDetail.providerIspbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco 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, que pode ser "STORE" ou "OTHER_BUSINESSES".
qrCodePurposestringRazã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": "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 CodeCódigoMensagemDescrição
400QRCODE_CANNOT_BE_DECODEDThe QrCodePayload is invalid or cannot be decoded. Check it out with the PSP.O QR Code não pode ser decodificado.
400INVALID_USER_IDEnsure 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.
400QRCODE_PAYLOAD_LOCATION_REMOVEDThe 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.
400REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIODRequest not not allowed out of business period.Não está disponível fora do horário comercial.
400ENTRY_NOT_FOUNDEntry not found.A chave que está sendo usada para gerar o QR Code não existe.
400CASHOUT_LIMIT_NOT_ENOUGHSender does not have sufficient cash out limit.A transação excede o limite de valor da transferência.
408REQUEST_TIMEOUTTransaction 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 7 days ago

Copyright © 2021 Acesso Soluções de Pagamento S.A - Todos os direitos reservados