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 é limitado a 25 caracteres e não aceita nenhum caractere especial.
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 15 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.O valor máximo é de 15 caracteres para esse campo.
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ódigoDescrição
400INVALID_PARAMETERO valor informado para a chave é inválido.
400INVALID_PARAMETERO tipo de chave informado é inválido.
400INVALID_PARAMETERO campo city não pode estar vazio.
400INVALID_PARAMETERO campo city não aceita números ou caracteres especiais.
400INVALID_PARAMETERO valor informado para zipCode é inválido. Considere não utilizar máscara para o CEP.
400INVALID_PARAMETERO campo recipientName não pode estar vazio.
400INVALID_PARAMETERO campo conciliationId não aceita caracteres especiais.
400INVALID_PARAMETERO campo changeAmountType não pode apresentar o valor "NOT_ALLOWED", pois o campo amount é nulo.
400ENTRY_NOT_FOUNDA chave que está sendo informada para gerar um QR Code não existe.
400INVALID_QRCODE_PAYLOADO payload informado é inválido. Verifique se os campos foram preenchidos corretamente.
400QRCODE_ALREADY_EXISTSID de conciliação (conciliationID) já usado anteriormente.
422EMV_FIELD_LENGTH_OUT_OF_RANGEComprimento do campo EMV (Merchant Account Information) fora do intervalo permitido.

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.