Emissão QR Code dinâmico

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:

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:

Cabeçalhos (Headers)

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:

📘

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:

🚧

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:

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.