Emissão de 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 a emissão

Antes de emitir qualquer QR Code Pix, certifique-se de que a chave de endereçamento Pix esteja 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.

Endpoint

Para uso deste endpoint, é preciso preencher os seguintes campos obrigatórios:

• x-correlation-id: no header, informe um GUID v4, que deve ser gerado a cada nova requisição;
• recipientName: nome do recebedor da transação;
• addressingKey:
  • type: tipo de chave de endereçamento DICT (CPF, CNPJ ou EVP);
  • value: valor da chave escolhida.
• conciliationId: o ID de conciliação é uma informação utilizada para conciliação dos pagamentos. Ela permite que você identifique a qual QR Code um determinado pagamento pertence. Importante: esse campo deve ter no mínimo 26 e no máximo 35 caracteres, e não são aceitos caracteres especiais;
• payer: o único dado obrigatório do campo payer é o campo address, um objeto que contém os seguintes subcampos:
  • city: cidade do pagador;
  • zipCode: código postal do pagador.

Opcionalmente, informe:

• singlePayment: para que um QR Code possa ser utilizado apenas uma vez, esse campo deve ser preenchido com true. Se este campo não for enviado ou estiver como false, será possível utilizá-lo em mais de um pagamento;
• payer:
  • name: nome do pagador. Embora o nome do pagador não seja obrigatório, caso ele seja informado, será obrigatório informar seu documento (documentNumber);
  • documentNumber: documento do pagador. Se o documento do pagador for informado, seu nome deverá ser enviado (name);
  • type: tipo de pagador, que pode ser CUSTOMER (pessoa física) ou BUSINESS (pessoa jurídica). Caso esse campo não seja informado, o sistema assume que o tipo de pagador é CUSTOMER;
• changeAmountType: para que o usuário pagador possa alterar o valor a ser pago no momento da transação, esse campo deve ser preenchido com “ALLOWED”. Caso contrário, informe "NOT_ALLOWED". Se esse campo não for enviado, o sistema assumirá que não é permitida a alteração do valor a ser pago;
• amount: valor a ser pago. Caso esse campo não seja informado, o changeAmountType será automaticamente preenchido como “ALLOWED” e o usuário pagador poderá alterar o valor do QR Code;
• expiresAt: data e hora em que o QR Code deve expirar, no formato "YYYY-MM-DD 00:00:00". Caso esse campo não seja informado, o QR Code irá expirar em 24h;
• payerRequestText: texto que o pagador visualizará no momento da transação;
• additionalData: lista contendo um ou mais subcampos, criados pelo emissor, para descrever informações adicionais. Este valor é somente leitura.

curl --location--request POST 'https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/dynamic/payment' \ 
--header 'api-version: 1' \ 
--header 'x-bkly-pix-user-id: 36075268855' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer  
--data-raw '{ 
    "recipientName": "Peter Parker", 
    "addressingKey": { 
        "type": "CPF", 
        "value": "12345678900" 
    }, 
    "conciliationId": "bklyconciliation012345678910", 
    "singlePayment":  false, 
    "payer": {  
        "name": "Carol Denvers",
        "documentNumber": "00987654321", 
        "type": "CUSTOMER", 
        "address": { 
            "city": "Sao Paulo",  
            "zipCode": "04205000" 
        } 
    }, 
    "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"
        }
    ] 
}'

Retorno

Caso obtenha sucesso em sua requisição, você receberá um código em base64. Nele, há uma URL que contém todas as informações sobre o pagamento e o recebedor.

🚧

Importante

Cabe ao parceiro transformar o base64 em imagem.

{ 
    "encodedValue": "MDAwMjAxMjY5MjAwMTRici5nb3YuYmNiLnBpeDI1NzBxci1oLnNhbmRib3guYmFua2x5LmNvbS5ici9waXgvcXIvOWUxODk2ODQtMDc1Zi00NjRmLTg2NzEtZTQ4MGNiYTA5MTZlNTIwNDAwMDA1MzAzOTg2NTgwMkJSNTkyMkd1aWxoZXJtZSBTY2hvbHogUmFtb3M2MDA5U2FvIFBhdWxvNjEwODA0MjA1MDAwNjIwNzA1MDMqKio2MzA0NDQ5Mg==" 
}

Erros