Pix Automático na Conta Pagadora

Esta página é para quem oferece contas Delfinance aos próprios clientes (BaaS) e precisa que esses clientes paguem via Pix Automático. Nesse caso, o seu app faz o papel do app do banco do pagador: mostra a recorrência, coleta a autorização e permite gerenciá-la. Se você só cobra os seus clientes, este conteúdo não se aplica. Veja a visão geral.

Todas as rotas de escrita desta página exigem o header IdempotencyKey, com um valor novo a cada chamada.

O que o seu app precisa oferecer

O Banco Central exige que o app do pagador:

mostre os dados da recorrência antes da autorização: recebedor, contrato, periodicidade, valor e datas;
permita definir e alterar um valor máximo em recorrências de valor variável;
liste as autorizações pendentes, ativas e o histórico;
permita cancelar a autorização a qualquer momento e um débito agendado até 23h59 da véspera.

Veja as regras completas em Regras e prazos.

Jornadas 2, 3 e 4: ler o QR Code

Leia o QR Code pelo mesmo endpoint de pagamento por QR Code. Quando o código traz uma recorrência, a resposta tem type igual a COMPOSITE, um decodeType de recorrência e o objeto recurrence.

curl --location 'https://apisandbox.delbank.com.br/baas/api/v2/pix/qrcode/payment-initialization' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
    "payload": "00020101021226...80...6304A1B2"
}'

{
    "endToEndId": "E3822485720261027135161U0X5D1POK",
    "type": "COMPOSITE",
    "decodeType": "RECURRENCE_DUE_DATE",
    "amount": 189.90,
    "recurrence": {
        "id": "RR3822485720261027AB12CD34EF5",
        "journey": 4,
        "frequencyType": "MONTHLY",
        "recurrenceStartDate": "2026-12-10",
        "amount": 189.90,
        "beneficiary": {
            "ispb": "38224857",
            "document": "11222333000181",
            "name": "ESCOLA EXEMPLO LTDA"
        },
        "debtor": {
            "type": "NATURAL",
            "document": "12345678901",
            "name": "Joao da Silva"
        },
        "contractNumber": "MAT-00012345",
        "contractDescription": "Mensalidade escolar",
        "retryCount": 1,
        "receiverPspUrl": "pix-h.delbank.com.br/v1/rec/vcharge63c589259ef54f"
    }
}

`decodeType`	Jornada	O que fazer
`RECURRENCE`	2	Mostrar a recorrência e pedir a autorização. Não há pagamento
`RECURRENCE_IMMEDIATE`	3	Pagar e autorizar no mesmo passo, com a ciência explícita do pagador
`RECURRENCE_DUE_DATE`	4	Pagar a cobrança. Depois, oferecer a adesão, que é opcional
`RECURRENCE_STATIC`	4	Pagar o QR estático. Depois, oferecer a adesão

Os valores QR_CODE_STATIC, QR_CODE_IMMEDIATE e QR_CODE_DUE_DATE indicam um QR Code comum, sem recorrência.

Registrar a autorização (jornadas 2 e 4)

Quando o pagador aceitar, registre a autorização com os dados de recurrence:

curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/pix/automatic/authorizations/RR3822485720261027AB12CD34EF5/approve' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{apiKey}}' \
--header 'IdempotencyKey: {{$guid}}' \
--data '{
    "journey": 4,
    "frequencyType": "MONTHLY",
    "recurrenceStartDate": "2026-12-10",
    "amount": 189.90,
    "beneficiary": {
        "ispb": "38224857",
        "document": "11222333000181",
        "name": "ESCOLA EXEMPLO LTDA"
    },
    "debtor": {
        "type": "NATURAL",
        "document": "12345678901",
        "name": "Joao da Silva"
    },
    "contractNumber": "MAT-00012345",
    "contractDescription": "Mensalidade escolar"
}'

{
    "recurrenceId": "RR3822485720261027AB12CD34EF5",
    "requestedAt": "2026-10-27T16:10:03.881"
}

Copie journey, frequencyType, as datas, amount ou minPayerMaxAmount, beneficiary, debtor, contractNumber e contractDescription da leitura do QR Code.
beneficiary é obrigatório.
Em recorrências de valor variável, informe em payerMaxAmount o valor máximo escolhido pelo pagador.
Os dados do pagador vêm da conta autenticada. Não é preciso enviá-los.

Jornada 1: responder uma solicitação

As solicitações da jornada 1 chegam como autorizações pendentes. Liste-as com flow=0 e authorizationResult=PENDING_USER em Listar autorizações e mostre ao pagador.

curl --location --request PUT 'https://apisandbox.delbank.com.br/baas/api/v1/pix/automatic/authorizations/RR3822485720261027B7C8D9E0F1A' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{apiKey}}' \
--header 'IdempotencyKey: {{$guid}}' \
--data '{
    "authorizationResult": true,
    "payerMaxAmount": 150.00
}'

curl --location --request PUT 'https://apisandbox.delbank.com.br/baas/api/v1/pix/automatic/authorizations/RR3822485720261027B7C8D9E0F1A' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{apiKey}}' \
--header 'IdempotencyKey: {{$guid}}' \
--data '{
    "authorizationResult": false,
    "rejectionReason": "Nao reconheco o recebedor"
}'

A resposta tem o mesmo formato: recurrenceId e requestedAt. Ao recusar, informe o motivo em rejectionReason. O Banco Central prevê dois motivos: o pagador não reconhece o recebedor ou não tem interesse.

Alterar o valor máximo

O pagador pode alterar o valor máximo a qualquer momento. A mudança vale para os próximos agendamentos, não para os já feitos.

curl --location --request PUT 'https://apisandbox.delbank.com.br/baas/api/v1/pix/automatic/authorizations/RR3822485720261027B7C8D9E0F1A/max-amount' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{apiKey}}' \
--header 'IdempotencyKey: {{$guid}}' \
--data '{
    "newPayerMaxAmount": 200.00
}'

{
    "recurrenceId": "RR3822485720261027B7C8D9E0F1A",
    "requestedAt": "2026-10-27T16:22:51.003Z"
}

A API não compara o novo valor com o minPayerMaxAmount da recorrência. Valide no seu app que o valor máximo não fica abaixo desse piso.

Débitos agendados

Para listar os débitos agendados do pagador, use Listar agendamentos com flow=1. No dia do vencimento, o débito é feito automaticamente, entre 0h e 8h, e gera o webhook PIX_PAYMENT_UPDATED como um Pix enviado. Para cancelar uma autorização ou um débito agendado, veja Cancelar. Use cancellationRequesterType igual a PAYER e cancellationReason igual a REQUESTED_BY_PAYER.

Referência da API

Registrar autorização

POST /baas/api/v1/pix/automatic/authorizations/{recurrenceId}/approve

Responder solicitação

PUT /baas/api/v1/pix/automatic/authorizations/{recurrenceId}

Alterar valor máximo

PUT /baas/api/v1/pix/automatic/authorizations/{recurrenceId}/max-amount

Ler QR Code

POST /baas/api/v2/pix/qrcode/payment-initialization

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

Pix Automático na Conta Pagadora

O que o seu app precisa oferecer

Jornadas 2, 3 e 4: ler o QR Code

Registrar a autorização (jornadas 2 e 4)

Jornada 1: responder uma solicitação

Alterar o valor máximo

Débitos agendados

Referência da API

Registrar autorização

Responder solicitação

Alterar valor máximo

Ler QR Code

​O que o seu app precisa oferecer

​Jornadas 2, 3 e 4: ler o QR Code

​Registrar a autorização (jornadas 2 e 4)

​Jornada 1: responder uma solicitação

​Alterar o valor máximo

​Débitos agendados

​Referência da API

Registrar autorização

Responder solicitação

Alterar valor máximo

Ler QR Code

O que o seu app precisa oferecer

Jornadas 2, 3 e 4: ler o QR Code

Registrar a autorização (jornadas 2 e 4)

Jornada 1: responder uma solicitação

Alterar o valor máximo

Débitos agendados

Referência da API