Jornada 3: Pagamento Imediato e Autorização

Na jornada 3, o QR Code junta uma cobrança imediata e a recorrência. Ao pagar, o pagador autoriza o Pix Automático no mesmo comando, depois de marcar que está ciente da adesão. Não dá para pagar sem autorizar. A autorização só vale se o pagamento for liquidado. Se o QR Code expirar ou o pagamento falhar, a recorrência não é ativada.

Quando usar

Adesão com primeiro pagamento

Checkout de assinatura em que o cliente paga o primeiro mês na hora e já deixa os próximos no automático.

Taxa de adesão

Matrícula, instalação ou ativação cobrada na adesão, seguida de mensalidades recorrentes.

O pagamento imediato é um Pix comum. Ele chega pelo webhook PIX_RECEIVED e não conta como parcela da recorrência. A primeira cobrança recorrente é a de recurrenceData.recurrenceStartDate.

Passo a passo

Crie o QR Code composto

Informe os dados da cobrança imediata na raiz do body e os dados da recorrência em recurrenceData.

curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/pix/qrcode/recurrences/immediate-payment' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
    "responseFormat": "PAYLOAD_AND_QRCODE",
    "key": "e7c3d5f2-4a1b-4c3d-9d15-1b2c3d4e5f60",
    "city": "Sao Paulo",
    "originalAmount": 49.90,
    "payerRequest": "Plano Premium - primeiro mes",
    "qrExpiration": 3600,
    "recurrenceData": {
        "recurrenceId": "RR3822485720261027F6E5D4C3B2A",
        "frequencyType": "MONTHLY",
        "recurrenceStartDate": "2026-11-27",
        "debtor": {
            "type": "NATURAL",
            "document": "12345678901",
            "name": "Joao da Silva"
        },
        "amount": 49.90,
        "contractNumber": "CTR-123456",
        "contractDescription": "Plano Premium",
        "retry": "ALLOWED"
    }
}'

{
    "documentId": "01000000-3353-6e2c-12c9-08de9f179024",
    "revision": "0",
    "qrCodeImageBase64": "iVBORw0KGgoAAAANSUhEUgAAASQAAAEkAQAAAACugnFBAAAD60lEQVR4nO2a...",
    "payloadBase64": "MDAwMjAxMjYxODAwMTRici5nb3YuYmNiLnBpeDUyMDQwMDAw...",
    "payloadPix": "00020101021226...80...6304A1B2",
    "payloadJws": "eyJhbGciOiJQUzUxMiIsImtpZCI6...",
    "compositePayloadJws": null,
    "recurrencePayloadJws": "eyJhbGciOiJQUzUxMiIsImtpZCI6IjE0NzhFNDZB..."
}

A chave Pix em key precisa ser da sua conta.

Exiba o QR Code

Mostre a imagem de qrCodeImageBase64 e o payloadPix como Pix Copia e Cola. O qrExpiration define por quanto tempo o pagador pode pagar e autorizar. O padrão é 24 horas.

Receba o pagamento

Quando o pagador paga, você recebe o webhook PIX_RECEIVED, como em qualquer Pix. A partir daí, a recorrência está autorizada.

Acompanhe as cobranças recorrentes

A Delfinance envia automaticamente a cobrança de cada ciclo, entre 10 e 2 dias antes do vencimento, a partir de recurrenceStartDate. Veja Cobranças recorrentes.

Dados da cobrança imediata

Campo	Obrigatório	Descrição
`key`	Sim	Chave Pix da sua conta que recebe o pagamento. Até 77 caracteres
`originalAmount`	Sim	Valor do pagamento imediato
`city`	Sim	Cidade do recebedor, até 15 caracteres
`qrExpiration`	Não	Validade em segundos. Padrão: `86400` (24 horas)
`changeValue`	Não	`NOT_ALLOWED` (padrão) ou `ALLOWED`, se o pagador pode alterar o valor
`payerRequest`	Não	Mensagem exibida ao pagador, até 140 caracteres
`payerDocument` / `payerName`	Não	CPF ou CNPJ e nome do pagador esperado
`additionalData`	Não	Lista de `{ "name", "value" }` exibida ao pagador

Os campos de recurrenceData são os mesmos da jornada 2: periodicidade, datas, valor fixo ou piso do valor máximo, devedor, contrato e retentativa.

Envie todos os campos obrigatórios de recurrenceData: frequencyType, recurrenceStartDate, debtor, contractNumber e retry. Hoje, a falta de um deles dentro de recurrenceData retorna 500 em vez de um erro de validação.

Referência da API

Criar QR Code com pagamento imediato

POST /baas/api/v1/pix/qrcode/recurrences/immediate-payment

Introdução

Autenticação

Receber via Pix (Pix Cash-in)

Pagar via Pix (Pix Cash-out)

Pix Automático

Pagar via TED (TED Cash-out)

Pagar boletos e contas (Cash-out)

Cobranças via Boleto

Split de Pagamentos

Saldo e extrato

Webhooks

Jornada 3: Pagamento Imediato e Autorização

Quando usar

Adesão com primeiro pagamento

Taxa de adesão

Passo a passo

Dados da cobrança imediata

Referência da API

Criar QR Code com pagamento imediato

​Quando usar

Adesão com primeiro pagamento

Taxa de adesão

​Passo a passo

​Dados da cobrança imediata

​Referência da API

Criar QR Code com pagamento imediato

Quando usar

Passo a passo

Dados da cobrança imediata

Referência da API