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:

• Logo após seu pagamento (QR Code de pagamento único);
• Na data e hora configuradas no momento de sua emissão;
• 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 (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/pix/qrCodeDynamic

--request POST 'https://sandbox.hiperbanco.com.br/pix/qrCodeDynamic' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "addressingKey": {
    "type": "EVP",
    "value": "9b4f0a1d-52a7-4fd1-9d2f-b4d8c6e3a000"
  },
  "conciliationId": "X9Y8Z7W6V5U4T3S2R1Q0P0N0M",
  "singlePayment": true,
  "recipientName": "Lucas Andrade",
  "expiresAt": "2026-02-28 02:21:40",
  "payer": {
    "name": "Ana Pereira",
    "documentNumber": "12345678909",
    "type": "CUSTOMER",
    "address": {
      "addressLine": "Rua das Flores, 123",
      "state": "SP",
      "city": "Campinas",
      "zipCode": "13050-001"
    }
  },
  "changeAmountType": "ALLOWED",
  "amount": 700
}'

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:

Chave de endereçamento

📘

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": "EVP",
    "value": "a1b2c3d4-e5f6-7890-abcd-1234567890ef"
  },
  "conciliationId": "ZXC123VBN456QWE789TYU0PLKM",
  "singlePayment": true,
  "recipientName": "Fernanda Oliveira",
  "expiresAt": "2026-03-15 14:30:00",
  "payer": {
    "name": "João Souza",
    "documentNumber": "01234567890",
    "type": "CUSTOMER",
    "address": {
      "addressLine": "Av. Central, nº 456",
      "state": "RJ",
      "city": "Niterói",
      "zipCode": "24360-000"
    }
  },
  "changeAmountType": "ALLOWED",
  "amount": 700
}

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==" 
} 

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 que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são: