Skip to main content
O QR Code Dinâmico é gerado por cobrança: cada pedido tem o seu próprio código, com valor definido e prazo de expiração. Assim que o pagador escaneia e paga, o QR Code fica indisponível, ele não pode ser reutilizado. Essa unicidade é exatamente o que permite ao seu sistema saber qual pedido foi pago sem nenhuma ambiguidade: o correlationId que você escolheu na criação chega de volta no evento de webhook, amarrado àquele pagamento específico.

​
Quando usar

Checkout de e-commerce

Gere um QR Code por pedido no momento do checkout. Quando o webhook chegar com o correlationId, você sabe exatamente qual pedido baixar, sem conciliação manual.

Cobranças avulsas

Envie um link de pagamento por e-mail, WhatsApp ou SMS. O QR Code expira no prazo que você definir, evitando pagamentos tardios indesejados.
Se você precisa de um código reutilizável, sem expiração, capaz de receber múltiplos pagamentos, use a Cobrança Reutilizável (QR Estático) em vez desta.

​
Passo a passo

1

Crie o QR Code Dinâmico

O mínimo necessário é o correlationId e o amount. Por padrão, o QR Code expira em 24 horas (86.400 segundos), mas você pode reduzir esse prazo com o campo expiresIn.
curl --location 'https://apisandbox.delbank.com.br/baas/api/v2/pix/qrcode/dynamic' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
    "correlationId": "{{$guid}}",
    "amount": 99.90
}'

{
    "correlationId": "40ede975-031d-4517-bdd4-31472d3f00a4",
    "transactionId": "vchargeffab8b4c963344c283e491f5e",
    "amount": 99.90,
    "allowChangeAmount": false,
    "expiresIn": 86400,
    "status": "ACTIVE",
    "address": {
        "cityName": "ARACAJU",
        "zipCode": "49000000",
        "uf": "SE",
        "state": "SE",
        "street": "LOGRADOURO"
    },
    "createdAt": "2024-12-10T13:19:26.501Z",
    "updatedAt": "2024-12-10T13:19:26.501Z",
    "expiresAt": "2024-12-11T13:19:26.501Z",
    "payloadPix": "00020101021226820014br.gov.bcb.pix2560pix-h.delbank.com.br/v2/cob/vchargeffab8b4c963344c283e491f5e5204000053039865802BR5907DELBANK6007ARACAJU62070503***6304CB42"
}
Para checkouts, você normalmente vai querer um prazo mais curto e já receber a imagem do QR Code pronta:
{
    "correlationId": "{{$guid}}",
    "amount": 99.90,
    "expiresIn": 1800,
    "formatResponse": "PAYLOAD_AND_QRCODE"
}
Use "formatResponse": "PAYLOAD_AND_QRCODE" para receber o campo qrCodeImageBase64 com a imagem já pronta (250×250 px). O padrão é ONLY_PAYLOAD, que omite a imagem e deixa você renderizar o QR Code a partir do payloadPix.
2

Exiba o QR Code para o pagador

A resposta traz tudo que você precisa para apresentar a cobrança:
  • payloadPix, o código “Pix Copia e Cola”, para quem prefere colar manualmente no app do banco.
  • qrCodeImageBase64, imagem pronta do QR Code, disponível quando formatResponse é PAYLOAD_AND_QRCODE.
  • expiresAt, o instante exato de expiração; use para exibir um contador regressivo na tela de checkout.
Disponibilize sempre as duas opções (imagem e copia-e-cola). Pagadores em desktop ou com câmera indisponível dependem do copia-e-cola.
3

Receba a confirmação via Webhook

Quando o pagamento é liquidado, a API dispara o evento PIX_RECEIVED para a URL de webhook que você configurou. Esse evento carrega o correlationId que você definiu na criação, use-o para identificar qual pedido foi pago e acionar a baixa no seu sistema.Veja Processando a confirmação via Webhook para o passo a passo completo de tratamento desse evento.
4

Consulte o status quando necessário

A qualquer momento você pode buscar o estado de uma cobrança pelo correlationId ou pelo transactionId:
cURL
curl --location 'https://apisandbox.delbank.com.br/baas/api/v2/pix/qrcode/dynamic/{{correlationId}}' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}'
Quando o pagamento já tiver sido realizado, a resposta inclui o array payments com todos os detalhes da transação: endToEndId, dados do pagador real, valor e horário de liquidação.
Não use consulta por polling como mecanismo principal de confirmação de pagamento. Os webhooks existem para eliminar essa necessidade. Use a consulta apenas para reconciliação ou recuperação de falhas pontuais.
5

Cancele se o pedido for cancelado

Se o pedido for cancelado antes do pagamento, cancele o QR Code para impedir que o cliente consiga pagar depois:
cURL
curl -X 'PATCH' \
  'https://apisandbox.delbank.com.br/baas/api/v2/pix/qrcode/dynamic/{{transactionId}}/cancel' \
  --header 'x-delbank-api-key: {{apiKey}}' \
  --header 'x-delfinance-account-id: {{accountId}}'
A operação retorna HTTP 202 sem corpo. QR Codes já expirados não precisam ser cancelados manualmente.

​
Funcionalidades avançadas

​
Restringir o pagamento a um pagador específico

Você pode vincular o QR Code a um CPF ou CNPJ específico. Com payer.validate: true, o código só será aceito quando o pagador que escanear for exatamente aquela pessoa. 
{
    "correlationId": "{{$guid}}",
    "amount": 150.00,
    "payer": {
        "name": "João Alves",
        "document": "47779921018",
        "validate": true
    }
}

​
Split de pagamento

Distribua parte do valor recebido para outra conta automaticamente no momento da criação. Útil para marketplaces e plataformas que precisam repassar comissões sem transferências manuais. 
{
    "correlationId": "{{$guid}}",
    "amount": 200.00,
    "splitInstructions": [
        {
            "accountNumber": "10073",
            "type": "PERCENTAGE",
            "amount": 10
        }
    ]
}
O type aceita PERCENTAGE (porcentagem do total) ou FIXED (valor fixo em reais).
O split só funciona se o amount for maior que R$ 1,00, e o total das divisões não pode ultrapassar 50% do valor da cobrança.

​
Beneficiário final (para gateways)

Se você opera como gateway ou subadquirente, use finalBeneficiary para indicar o recebedor final da transação. Esse dado é exibido ao pagador no app do banco no momento do pagamento. 
{
    "correlationId": "{{$guid}}",
    "amount": 300.00,
    "finalBeneficiary": {
        "name": "João Silva",
        "document": "12345678901",
        "cityName": "São Paulo"
    }
}

​
Referência da API

Criar

POST /pix/qrcode/dynamic

Consultar

GET /pix/qrcode/dynamic/:id

Cancelar

PATCH /pix/qrcode/dynamic/:id/cancel