Cobrança recorrente com PIX Automático

O PIX Automático permite que um cliente autorize um débito recorrente uma única vez, no próprio banco, e depois o Portão 3 coleta cada cobrança automaticamente. Você cria uma autorização, envia o cliente para a página de aprovação dela e depois acompanha a autorização e as cobranças por webhooks ou consultando-as. Este guia também cobre como alterar o valor de uma cobrança, cancelar e recorrer ao boleto quando uma cobrança falha.

Fluxo

Etapa 1: Criar a autorização

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-billing-automatic' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Monthly subscription",
    "pixDict": "financeiro@suaempresa.com.br",
    "debitParty": {
      "type": "INDIVIDUAL",
      "name": "FULL NAME OF CUSTOMER",
      "email": "customer@email.com",
      "document": "12345678909"
    },
    "schedule": {
      "type": "MONTHLY",
      "minAmount": 50000,
      "maxAmount": 50000,
      "startDate": "2026-12-10",
      "endDate": "2027-11-10"
    },
    "firstPayment": {
      "amount": 50000,
      "date": "2026-11-10",
      "description": "Setup charge"
    }
  }'

Campo	Observações
`pixDict`	Uma das chaves PIX ativas da carteira, como foi cadastrada: as cobranças são pagas a ela. Veja Carteiras para seus clientes.
`debitParty`	O cliente pagador. `type` é `INDIVIDUAL`, com o CPF em `document`, ou `BUSINESS`, com o CNPJ da empresa.
`schedule.type`	Recorrência: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMESTER` ou `YEARLY`.
`schedule.minAmount` / `maxAmount`	Centavos. A faixa que o cliente autoriza por cobrança; cada cobrança recorrente é criada com `minAmount`. Use os dois iguais para um valor fixo.
`schedule.startDate` / `endDate`	Obrigatórios. A data da primeira cobrança recorrente — pelo menos dois dias a partir de hoje, e depois de `firstPayment.date` — e o último dia em que uma cobrança pode cair.
`schedule.dates`	Opcional. Datas explícitas das cobranças, de `startDate` a `endDate`; sem ele (ou com uma lista vazia), uma cobrança cai em `startDate` e depois a cada intervalo até `endDate`.
`firstPayment`	Cobrança avulsa opcional, coletada na sua `date` depois que o cliente aprova (por exemplo, uma taxa de adesão): hoje ou depois, antes de `schedule.startDate`.
`callBackUrlForPaymentProvider`	Opcional. Páginas suas para onde o cliente volta (`success`, `pending`, `error`) depois da página de aprovação.

A resposta é 201 Created: a autorização, com status CREATED, o paymentUrl e todas as cobranças em schedules — o primeiro pagamento (isFirstPayment: true) e cada cobrança recorrente, todas CREATED:

{
  "_id": "6729f3e1b4d3e80012c9a7c1",
  "status": "CREATED",
  "paymentUrl": "https://pay.portao3.com.br/2d902e74-7ca0-4f6c-9c83-4b5e6f708192",
  "schedule": {
    "type": "MONTHLY",
    "minAmount": 50000,
    "maxAmount": 50000,
    "startDate": "2026-12-08T00:00:00.000Z",
    "endDate": "2027-11-11T00:00:00.000Z"
  },
  "schedules": [
    { "_id": "6729f3e1b4d3e80012c9a7d3", "amount": 50000, "isFirstPayment": true, "status": "CREATED", "scheduledTo": "2026-11-10T00:00:00.000Z" },
    { "_id": "6729f3e1b4d3e80012c9a7d4", "amount": 50000, "status": "CREATED", "scheduledTo": "2026-12-10T00:00:00.000Z" }
  ]
}

A autorização guarda as próprias datas: schedule.startDate é dois dias antes do schedule.startDate que você enviou — ou o dia seguinte ao primeiro pagamento, quando for depois — e schedule.endDate é o dia seguinte ao que você enviou. Redirecione o cliente para paymentUrl para aprovar a autorização no banco dele. Referência: POST .../wallets/{walletId}/pix-billing-automatic

Etapa 2: Acompanhar o ciclo de vida da autorização

Os eventos PIX_BILLING_AUTOMATIC_* acompanham a autorização em si (o consentimento que o cliente aprova):

Evento	Significado
`PIX_BILLING_AUTOMATIC_CREATED`	Você acabou de criá-la (`CREATED`).
`PIX_BILLING_AUTOMATIC_INITIATED`	O cliente começou a aprovação no banco (`INITIATED`).
`PIX_BILLING_AUTOMATIC_SCHEDULED`	O cliente aprovou a autorização (`SCHEDULED`); o primeiro pagamento, se houver, é cobrado na data dele.
`PIX_BILLING_AUTOMATIC_EXPIRED`	O cliente não aprovou antes de as primeiras cobranças vencerem (`EXPIRED`); as cobranças pendentes também expiram.
`PIX_BILLING_AUTOMATIC_CANCELED`	Você cancelou (`CANCELED`).

Quando o cliente revoga a autorização no banco, ela passa a REVOKED e as cobranças pendentes são canceladas; essa mudança não tem webhook, então consulte a autorização.

{
  "source": "WALLET",
  "event": "PIX_BILLING_AUTOMATIC_SCHEDULED",
  "payload": {
    "_id": "6729f3e1b4d3e80012c9a7c1",
    "status": "SCHEDULED",
    "paymentUrl": "https://pay.portao3.com.br/2d902e74-7ca0-4f6c-9c83-4b5e6f708192"
  }
}

Para consultá-la a qualquer momento, com todas as cobranças, use GET .../pix-billing-automatic/{pixBillingAutomaticId}.

Etapa 3: Acompanhar cada cobrança

Os eventos PIX_BILLING_AUTOMATIC_SCHEDULE_* acompanham as cobranças individuais:

Evento	Significado
`PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE`	A cobrança está prestes a ser enviada ao banco do cliente (o envio acontece de 2 a 10 dias antes da data dela).
`PIX_BILLING_AUTOMATIC_SCHEDULE_SCHEDULED`	A cobrança está agendada no banco do cliente (`SCHEDULED`).
`PIX_BILLING_AUTOMATIC_SCHEDULE_PAID`	A cobrança foi paga (`PAID`).
`PIX_BILLING_AUTOMATIC_SCHEDULE_FAILED`	A cobrança falhou e não será tentada de novo (`FAILED`); `error` diz o motivo.
`PIX_BILLING_AUTOMATIC_SCHEDULE_CANCELED`	A cobrança foi cancelada no banco do cliente (`CANCELED`).

{
  "source": "WALLET",
  "event": "PIX_BILLING_AUTOMATIC_SCHEDULE_PAID",
  "payload": {
    "_id": "6729f3e1b4d3e80012c9a7d4",
    "pixBillingAutomaticId": "6729f3e1b4d3e80012c9a7c1",
    "amount": 50000,
    "status": "PAID",
    "scheduledTo": "2026-12-10T00:00:00.000Z"
  }
}

Quando o banco do cliente não consegue debitar uma cobrança, o Portão 3 pede uma nova tentativa um ou dois dias depois — até três tentativas no total, contando a da data de vencimento, cada uma listada em attempts da cobrança — a menos que a recusa seja definitiva (por exemplo, o limite do cliente para o período foi atingido). Aí a cobrança passa a FAILED. Uma cobrança que o banco do cliente se recusa a agendar não tem webhook: ela termina como SCHEDULE_ERROR, ou continua CREATED depois da data dela, sem external.scheduleId e com um evento SCHEDULE_ATTEMPT_FAILED no histórico. Se você depende de webhooks, consulte também as cobranças da carteira com status=SCHEDULE_ERROR (trate como FAILED) e com status=CREATED e um maxDueDate no passado. Uma cobrança CREATED assim provavelmente foi recusada — mas, em casos raros, o banco do cliente aceitou e a confirmação se perdeu; então confirme com o suporte do Portão 3 antes de cobrá-la de outra forma. Uma cobrança CREATED depois da data que tem external.scheduleId ainda está sendo processada pelo banco do cliente: espere o resultado — não a cobre de outra forma. Para ver o que vence e o que foi pago em todas as autorizações da carteira, use GET .../wallets/{walletId}/pix-billing-automatic/schedules, filtrando por status e data de vencimento. Os eventos de uma autorização — a criação e os cancelamentos, cada atualização do banco do cliente, com o erro — estão em GET .../pix-billing-automatic/{pixBillingAutomaticId}/history.

Alterar o valor de uma cobrança

Ajuste uma cobrança individual (por exemplo, uma cobrança parcial) atualizando-a, referenciando tanto o ID da autorização quanto o ID da cobrança:

curl -X PUT \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-billing-automatic/{pixBillingAutomaticId}/schedules/{pixBillingAutomaticScheduleId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Partial charge",
    "amount": 35000
  }'

O novo amount (centavos) deve permanecer dentro da faixa minAmount/maxAmount da autorização; se for precisar, crie a autorização com uma faixa variável. Só uma cobrança recorrente que ainda não foi enviada ao banco do cliente (CREATED) pode mudar; o primeiro pagamento não, ele vai com a autorização. Referência: PUT .../pix-billing-automatic/{pixBillingAutomaticId}/schedules/{pixBillingAutomaticScheduleId}. Para listar e filtrar autorizações, use GET .../wallets/{walletId}/pix-billing-automatic.

Cancelar

Uma cobrança — POST .../schedules/{pixBillingAutomaticScheduleId}/cancel cancela a cobrança e mantém a autorização e as demais cobranças. O primeiro pagamento não pode ser cancelado sozinho antes de o cliente aprovar: cancele a autorização inteira.
A autorização inteira — POST .../pix-billing-automatic/{pixBillingAutomaticId}/cancel encerra a autorização: nenhuma outra cobrança é feita, e as cobranças ainda CREATED ou SCHEDULED são canceladas.

Uma cobrança já enviada ao banco do cliente não pode ser cancelada na data dela ou depois. As duas respondem 204 No Content.

Recorrer a boleto em caso de falhas repetidas

Quando as cobranças continuam falhando (FAILED ou SCHEDULE_ERROR), emita um boleto pelo mesmo valor para que o cliente ainda possa pagar:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto-billing' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "txnCurrency": "986",
    "txnAmount": 50000,
    "txnDivergentAmountType": "NOT_ALLOW_DIFFERENT_AMOUNT",
    "dueDate": "2026-08-19",
    "expiresAt": "2026-08-31",
    "description": "Subscription — boleto fallback",
    "customer": {
      "name": "FULL NAME OF CUSTOMER",
      "document": "12345678909",
      "address": {
        "street": "AV LANDSCAPE",
        "number": "970",
        "neighborhood": "JARDIM SUL",
        "postalCode": "38411-694",
        "city": "UBERLANDIA",
        "state": "MG"
      }
    }
  }'

O boleto volta CREATED, com o digitableLine e o barcode para apresentar ao cliente — ou baixe o PDF com GET .../boleto-billing/{boletoId}/download/pdf. Raramente ele volta INITIATED, ainda sem eles: consulte-o até ficar CREATED. Uma cobrança por boleto não tem webhook, então consulte-a com GET .../boleto-billing/{boletoId} para saber quando ela fica PAID. Você também pode adicionar regras de desconto, multa e juros (txnDiscountAmount, txnFineAmount, txnInterestAmount) — veja Cobrar com boleto e a referência do endpoint para o corpo completo. Referência: POST .../wallets/{walletId}/boleto-billing

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Cobrança recorrente com PIX Automático

Fluxo

Etapa 1: Criar a autorização

Etapa 2: Acompanhar o ciclo de vida da autorização

Etapa 3: Acompanhar cada cobrança

Alterar o valor de uma cobrança

Cancelar

Recorrer a boleto em caso de falhas repetidas

Próximos passos

Receber webhooks

Cobrar com PIX

​Fluxo

​Etapa 1: Criar a autorização

​Etapa 2: Acompanhar o ciclo de vida da autorização

​Etapa 3: Acompanhar cada cobrança

​Alterar o valor de uma cobrança

​Cancelar

​Recorrer a boleto em caso de falhas repetidas

​Próximos passos

Receber webhooks

Cobrar com PIX

Fluxo

Etapa 1: Criar a autorização

Etapa 2: Acompanhar o ciclo de vida da autorização

Etapa 3: Acompanhar cada cobrança

Alterar o valor de uma cobrança

Cancelar

Recorrer a boleto em caso de falhas repetidas

Próximos passos