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 valortrue
.
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:
singlePayment | expiresAt | Comportamento esperado |
---|---|---|
true | null | O 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). |
false | null | O 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",
"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:
Scope | Descrição |
---|---|
pix.qrcode-dynamic-payment.create | Concede acesso para emissão de QR Code dinâmico para pagamentos via Pix. |
Cabeçalhos (Headers)
Nome | Descriçã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 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:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
recipientName | string | Nome do recebedor do pagamento. Campo obsoleto, não é necessário enviá-lo. | — |
addressingKey | object | Obrigatório. Objeto que contém informações sobre a chave de endereçamento DICT. | — |
addressingKey.type | string | Obrigatório. Tipo de chave de endereçamento DICT (CPF, CNPJ ou EVP). | — |
addressingKey.value | string | Obrigatório. Valor da chave escolhida. | — |
conciliationId | string | Obrigató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. |
singlePayment | boolean | Indica 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. | — |
payer | object | Obrigatório. Objeto que contém informações sobre o pagador. | — |
payer.name | string | Obrigatório. Nome do pagador. | O valor máximo é de 25 caracteres para esse campo. |
payer.documentNumber | string | Obrigatório. Documento do pagador. | — |
payer.type | string | Obrigatório. Tipo de pagador, que pode ser CUSTOMER (pessoa física) ou BUSINESS (pessoa jurídica). | — |
payer.address | object | Obrigatório. Objeto que contém informações sobre o endereço do pagador. | — |
payer.address.addressLine | string | Logradouro (Nome da rua, avenida etc.). | — |
payer.address.state | string | Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: SP. | — |
payer.address.city | string | Obrigató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.zipCode | string | Obrigatório. Código postal do endereço. | — |
amount | number | Campo que define o valor do pagamento. | — |
changeAmountType | string | Esse 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. | — |
expiresAt | string | Data 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" |
additionalData | array of objects | Lista 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",
"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:
Nome | Tipo | Descrição |
---|---|---|
encodedValue | string | Có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 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. |
400 | INVALID_QRCODE_PAYLOAD | The QrCodePayload is invalid. | O payload informado é inválido. Verifique se os campos foram preenchidos corretamente. |
400 | QRCODE_ALREADY_EXISTS | QrCode cannot be generated because it already exists. | ID de conciliação (conciliationID ) já usado anteriormente. |
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. |
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 3 months ago