Emissão QR Code dinâmico

stable

QR Code dinâmico de pagamento imediato

O QR Code dinâmico de pagamento imediato tem como objetivo atender as necessidades de transacionar determinado valor em um momento próximo de sua data de emissão.

Ele traz informações sobre o recebedor da transação e permite que também sejam inseridas informações sobre o pagador do valor transacionado, para que posteriormente seja possível identificar os dados de quem efetuou o pagamento.

Além disso, esse tipo de QR Code possibilita que o emissor defina um valor fixo ou que o pagador edite a quantia a ser paga no momento de realizar a transação.

Pagamento múltiplo ou único

Por padrão, o mesmo QR Code dinâmico de pagamento imediato é utilizado para realizar mais de um pagamento em cobranças direcionadas a um ou mais pagadores.

No entanto, é possível que ele também seja utilizado para um único pagamento.

📘

Nota

Para que o QR Code dinâmico de pagamento imediato possa ser utilizado somente uma vez, é preciso que o campo singlePayment seja preenchido com o valor true.

Validade do QR Code

Diferentemente do QR Code estático, que não possui validade, o QR Code dinâmico de pagamento imediato apresenta um tempo de vida útil.

Dessa forma, o QR Code poderá expirar nos seguintes cenários:

  • logo após seu pagamento (QR Code de pagamento único);
  • na data e hora configuradas no momento de sua emissão ou
  • 24h a partir de sua emissão, caso o pagamento não tenha sido efetuado.

🚧

Importante

Para que o QR Code expire em 24h, o campo expiresAt não deve ser enviado na requisição.

Casos de uso

Veja a seguir as possibilidades de configuração para expiração do_ QR Code dinâmico de pagamento imediato:

singlePaymentexpiresAtComportamento esperado
truenullO QR Code irá expirar assim que for pago ou 24h após sua emissão (caso não tenha sido pago).
true"YYYY-MM-DD 00:00:00"O QR Code irá expirar assim que for pago ou na data e hora configuradas (caso não tenha sido pago).
falsenullO QR Code poderá ser utilizado para pagamento várias vezes dentro do período de 24h. Após esse período, ele irá expirar.
false"YYYY-MM-DD 00:00:00"O QR Code poderá ser utilizado para pagamento várias vezes dentro do período configurado. Após esse período, ele irá expirar.

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

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/dynamic/payment \ 
--location--request POST 'https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/dynamic/payment' \ 
--header 'api-version: 1' \ 
--header 'x-bkly-pix-user-id: 47742663023' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer  
--data-raw '{ 
    "recipientName": "Nísia Floresta", 
    "addressingKey": { 
        "type": "CPF", 
        "value": "47742663023" 
    }, 
    "conciliationId": "bklyconciliation0123456910", 
    "singlePayment":  false, 
    "payer": {  
        "name": "Nísia Floresta",
        "documentNumber": "47742663023", 
        "type": "CUSTOMER", 
        "address": { 
            "city": "Santarém",  
            "zipCode": "68060100" 
        } 
    }, 
    "amount": 55.42, 
    "changeAmountType": "NOT_ALLOWED", 
    "expiresAt": "2022-05-01 00:00:00", 
    "payerRequestText": "mensagem ao pagador", 
    "additionalData": [ 
        {
            "name": "mensagem info adicionais",
            "value": "mensagem de campo valor info adicionais"
        }
    ] 
}'

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-dynamic-payment.createConcede acesso para emissão de QR Code dinâmico para pagamentos via Pix.

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-bkly-pix-user-idObrigatório. Número do documento do cliente que está solicitando a leitura do QR Code. 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 os seguintes campos em formato JSON:

NomeTipoDescriçãoEspecificação
recipientNamestringNome do recebedor do pagamento.
Campo obsoleto, não é necessário enviá-lo.
addressingKeyobjectObrigatório. Objeto que contém informações sobre a chave de endereçamento DICT.
addressingKey.typestringObrigatório. Tipo de chave de endereçamento DICT (CPF, CNPJ ou EVP).
addressingKey.valuestringObrigatório. Valor da chave escolhida.
conciliationIdstringObrigatório. ID de conciliação é uma informação que pode ser passada na emissão do QR Code e utilizada para conciliação dos pagamentos.Esse campo deve ter no mínimo 26 e no máximo 35 caracteres, e não são aceitos caracteres especiais.
singlePaymentbooleanIndica se o QR Code deve ser utilizado apenas uma vez (TRUE). Se este campo não for enviado ou estiver como FALSE, será possível utilizá-lo em mais de um pagamento.
payerobjectObrigatório. Objeto que contém informações sobre o pagador.
payer.namestringObrigatório. Nome do pagador.O valor máximo é de 25 caracteres para esse campo.
payer.documentNumberstringObrigatório. Documento do pagador.
payer.typestringObrigatório. Tipo de pagador, que pode ser CUSTOMER (pessoa física) ou BUSINESS (pessoa jurídica).
payer.addressobjectObrigatório. Objeto que contém informações sobre o endereço do pagador.
payer.address.addressLinestringLogradouro (Nome da rua, avenida etc.).
payer.address.statestringSigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: SP.
payer.address.citystringObrigatório. Nome da cidade. Importante: Embora seja permitido ultrapassar 15 caracteres, ao ser decodificado, nomes de cidades com mais de 15 caracteres não serão exibidos integralmente.
payer.address.zipCodestringObrigatório. Código postal do endereço.
amountnumberCampo que define o valor do pagamento.
changeAmountTypestringEsse campo indica se o valor a ser pago pode (“ALLOWED”) ou não ("NOT_ALLOWED") ser alterado no momento da transação. Caso o campo seja preenchido com “ALLOWED”, não é necessário preencher o campo amount, que assumirá automaticamente o valor "0", permitindo a alteração do montante no momento da transação. Se o valor "NOT_ALLOWED" for informado, o campo amount deverá ser preenchido obrigatoriamente com o valor a ser transacionado.
expiresAtstringData e hora em que o QR Code deve expirar. Caso esse campo não seja informado, o QR Code irá expirar em 24h.Formato: "YYYY-MM-DD 00:00:00"
payerRequestTextstringTexto que o pagador visualizará no momento da transação.
additionalDataarray of objectsLista contendo um ou mais subcampos, criados pelo emissor, para descrever informações adicionais. Este valor é somente leitura.

📘

Nota

O campo expiresAt permite a definição do horário de expiração do QR Code, porém, a expiração efetiva ocorrerá somente no dia seguinte ao especificado.

Exemplo: se o usuário definir que o QR Code criado deve expirar em 20/10/2023 às 16:00:00, os pagamentos ainda poderão ser realizados até meia-noite (00:00h) do mesmo dia, uma vez que o QR Code só expirará no próximo dia, ou seja, a partir de 00:00h em 21/10/2023.

{ 
    "addressingKey": { 
        "type": "CPF", 
        "value": "47742663023" 
    }, 
    "conciliationId": "bklyconciliation0123456910", 
    "singlePayment":  false, 
    "payer": {  
        "name": "Nísia Floresta",
        "documentNumber": "47742663023", 
        "type": "CUSTOMER", 
        "address": { 
            "addressLine": "Rua 6 de Março",
            "state": "PA",
            "city": "Santarém",  
            "zipCode": "68060100" 
        } 
    }, 
    "amount": 55.42, 
    "changeAmountType": "NOT_ALLOWED", 
    "expiresAt": "2022-05-01 00:00:00", 
    "payerRequestText": "mensagem ao pagador", 
    "additionalData": [ 
        {
            "name": "mensagem info adicionais",
            "value": "mensagem de campo valor info adicionais"
        }
    ] 
}

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:

NomeTipoDescrição
encodedValuestringCódigo em base64, que contém uma URL com todas as informações sobre o pagamento e o recebedor.

🚧

Importante

Cabe ao parceiro transformar o base64 em imagem.

{ 
    "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 codeCódigoMensagemDescrição
400ENTRY_NOT_FOUNDEntry not found.A chave que está sendo informada para gerar um QR Code não existe.
400INVALID_QRCODE_PAYLOADThe QrCodePayload is invalid.O payload informado é inválido. Verifique se os campos foram preenchidos corretamente.
400QRCODE_ALREADY_EXISTSQrCode cannot be generated because it already exists.ID de conciliação (conciliationID) já usado anteriormente.
422EMV_FIELD_LENGTH_OUT_OF_RANGEEMV Merchant Account Information field length out of range allowed.Comprimento do campo EMV (Merchant Account Information) fora do intervalo permitido.

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.