Emissão de QR Code estático
stable
O QR Code estático foi planejado para ser utilizado em cobranças direcionadas a mais de um pagador. Ou seja, o mesmo QR Code pode ser usado várias vezes por pagadores diferentes.
Esse tipo de QR Code traz apenas informações sobre o recebedor do pagamento e possibilita definir um valor fixo ou editar o valor a ser pago pelo usuário pagador no momento de realizar a transação.
Nota
O QR Code estático não possui validade e nem está sujeito a multas e juros.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- A chave de endereçamento Pix seja válida. Caso contrário, não será possível fazer a emissão.
Importante
Se a chave de endereçamento atrelada ao QR Code for excluída após sua emissão, o QR Code ficará inválido para pagamento.
Requisição (Request)
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/static/transfer \
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/static/transfer' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'x-correlation-id: {{GUID}}' \
--header 'x-bkly-pix-user-id: {{clientDocument}}'\
--header 'Authorization: Bearer {{Token}}
--data-raw '{
"addressingKey": {
"type": "CPF",
"value": "47742663023"
},
"location": {
"city": "Santarém",
"zipCode": "68060100"
},
"amount": 1,
"recipientName": "Nísia Floresta",
"conciliationId": "45761a14-5afd-4ef6-beee-a580c39b3cc5"
}'
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.create | Concede acesso para emissão de QR Code estático para pagamentos via Pix. |
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 cliente que está solicitando a leitura do QR Code. | Insira 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 os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
addressingKey | object | Obrigatório. Objeto que deverá conter informações sobre a chave de endereçamento. | — |
addressingKey.type | string | Obrigatório. Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE", "EMAIL" ou "EVP". | — |
addressingKey.value | string | Obrigatório. Valor da chave. | Consulte a tabela Chave de endereçamento para obter instruções de preenchimento deste campo. |
location | object | Obrigatório. Objeto que deverá conter informações sobre a localidade do recebedor da transação. | — |
location.city | string | Obrigatório. Nome da cidade do recebedor da transação. | O valor máximo é de 15 caracteres para esse campo. |
location.zipCode | string | Obrigatório. Código postal do recebedor da transação. | — |
amount | number | Valor do QR Code gerado. | — |
recipientName | string | Nome do recebedor da transação. Campo Obsoleto , não é necessário enviá-lo. | — |
conciliationId | string | Identificador utilizado para conciliação dos pagamentos. Importante: para obter o conciliationID na decodificação do QR Code estático, envie-o nesta requisição. | Esse campo é limitado a 25 caracteres e não aceita nenhum caractere especial. |
categoryCode | string | MCC (Merchant Category Code) é um número de quatro dígitos listado na ISO 18245 para serviços financeiros de varejo. Caso o usuário recebedor o possua, ele deve ser informado. Valor default: 0000. | — |
additionalData | string | Campo livre para informações adicionais. | Seu tamanho máximo é definido por 73 subtraído o tamanho da chave. Considerando que uma chave tem o tamanho mínimo de 9 caracteres, o tamanho máximo deste campo é 64. Além disso, este campo não aceita caracteres especiais. |
Chave de endereçamento
Chave | Instrução de preenchimento |
---|---|
CPF | 11 dígitos, sem formatação. |
CNPJ | 14 dígitos, sem formatação. |
Todos os caracteres em minúsculo. Tamanho máximo de 72 caracteres. | |
PHONE | Número de telefone celular, composto por símbolo ‘+’, seguido pelo código do país, DDD e número de celular com até nove dígitos. Ex.: +5523415162342. |
EVP | Tamanho máximo de 36 caracteres. Exemplo: 123e4967-e89b-12d3-a456-426655440000. |
{
"addressingKey": {
"type": "CPF",
"value": "47742663023"
},
"location": {
"city": "Santarém",
"zipCode": "68060100"
},
"amount": 1,
"conciliationId": "45761a14-5afd-4ef6-beee-a580c39b3cc5",
"categoryCode": "0000",
"additionalData": "string"
}
Resposta (Response)
O status code 200 indicará que a solicitação foi aceita com sucesso.
Sendo bem-sucedido, o retorno irá trazer o seguinte campo em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
encodedValue | string | Código em base64, que contém todas as informações sobre o pagamento. |
{
"encodedValue": "MDAwMjAxMjYzMzAwMRici5nb3YuYmNiLnBpeDAxMTEwNTY3ODQwNDg0OTUyMDQwMDAwNTMwMzk4NjU0MDUxMC4wMTU4MDJCUjU5MTVGZXJuYW5kbyBTZWd1aW02MDA5U2FvIFBhdWxvNjEwODA0MjA1MDAwNjIwNzA1MDMqKio2MzA0Njc5Ng=="
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
Status code | Código | Mensagem | Descrição |
---|---|---|---|
400 | ENTRY_NOT_FOUND | Entry not found. | A chave que está sendo informada para gerar um QR Code não existe. |
408 | REQUEST_TIMEOUT | Transaction exceeded request limit timeout. | A requisição excedeu o tempo limite da solicitação. |
422 | EMV_FIELD_LENGTH_OUT_OF_RANGE | EMV Merchant Account Information field length out of range allowed. | Comprimento do campo EMV (Merchant Account Information) fora do intervalo permitido. |
422 | ADDRESSING_KEY_NOT_FOUND | The addressing key informed was not found for this account. | A chave Pix informada não está cadastrada na conta que está sendo usada pra gerar o QR Code. |
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