Cobrança recorrente com PIX Automático

O PIX Automático permite que um cliente autorize um débito recorrente uma única vez, e depois o Portão 3 coleta cada ciclo automaticamente. Você cria uma autorização, envia o cliente para uma página de aprovação hospedada e depois acompanha o ciclo de vida por webhooks. Este guia também cobre como alterar o valor de um ciclo 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": "bd4ae8f9-94e3-4bea-97ce-869f11f058aa",
    "debitParty": {
      "type": "INDIVIDUAL",
      "name": "FULL NAME OF CUSTOMER",
      "email": "customer@email.com",
      "document": "CPF OF CUSTOMER"
    },
    "schedule": {
      "type": "MONTHLY",
      "minAmount": 50000,
      "maxAmount": 50000,
      "startDate": "2026-07-01",
      "endDate": "2027-06-01"
    },
    "firstPayment": {
      "amount": 50000,
      "date": "2026-06-15",
      "description": "Setup charge"
    }
  }'

Campo	Observações
`pixDict`	A chave PIX (DICT) que receberá as cobranças. Veja Carteiras para seus clientes.
`debitParty`	O cliente pagador. `type` é `INDIVIDUAL`; `document` é o CPF.
`schedule.type`	Recorrência: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMESTER` ou `YEARLY`.
`schedule.minAmount` / `maxAmount`	Centavos. A faixa autorizada por ciclo; defina os dois iguais para um valor fixo.
`schedule.startDate` / `endDate`	As datas do primeiro e do último ciclo.
`firstPayment`	Cobrança avulsa opcional feita antecipadamente (por exemplo, uma taxa de setup).

A resposta retorna a autorização com um paymentUrl e os schedules gerados:

{
  "_id": "685aedd2f85ed96059637958",
  "status": "SCHEDULED",
  "paymentUrl": "https://pay.portao3.com.br/c41dcc54-ddae-41b0-8f82-5c79da0ec833",
  "schedule": { "type": "MONTHLY", "minAmount": 50000, "maxAmount": 50000 },
  "schedules": [
    { "_id": "685a...795b", "amount": 50000, "status": "CREATED", "scheduledTo": "2026-07-01T00:00:00.000Z" }
  ]
}

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 contrato que o cliente aprova):

Evento	Significado
`PIX_BILLING_AUTOMATIC_CREATED`	Você acabou de criá-la.
`PIX_BILLING_AUTOMATIC_INITIATED`	O cliente abriu o banco para revisá-la.
`PIX_BILLING_AUTOMATIC_SCHEDULED`	O cliente aprovou a autorização.
`PIX_BILLING_AUTOMATIC_EXPIRED`	O cliente não aprovou a tempo — o link é reativado para uma nova tentativa.
`PIX_BILLING_AUTOMATIC_CANCELED`	Você ou o cliente cancelou.

{
  "source": "WALLET",
  "event": "PIX_BILLING_AUTOMATIC_SCHEDULED",
  "payload": {
    "_id": "685aedd2f85ed96059637958",
    "status": "SCHEDULED",
    "paymentUrl": "https://pay.portao3.com.br/c41dcc54-ddae-41b0-8f82-5c79da0ec833"
  }
}

Etapa 3: Acompanhar cada ciclo

Os eventos PIX_BILLING_AUTOMATIC_SCHEDULE_* acompanham as cobranças individuais (uma por ciclo):

Evento	Significado
`PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE`	O ciclo foi criado.
`PIX_BILLING_AUTOMATIC_SCHEDULE_SCHEDULED`	A cobrança está agendada no banco.
`PIX_BILLING_AUTOMATIC_SCHEDULE_PAID`	O ciclo foi pago.
`PIX_BILLING_AUTOMATIC_SCHEDULE_FAILED`	A cobrança falhou (após as retentativas).
`PIX_BILLING_AUTOMATIC_SCHEDULE_CANCELED`	Você ou o cliente cancelou o ciclo.

{
  "source": "WALLET",
  "event": "PIX_BILLING_AUTOMATIC_SCHEDULE_PAID",
  "payload": {
    "_id": "685aedd2f85ed9605963795b",
    "pixBillingAutomaticId": "685aedd2f85ed96059637958",
    "amount": 50000,
    "status": "PAID",
    "scheduledTo": "2026-07-01T00:00:00.000Z"
  }
}

O Portão 3 tenta novamente uma cobrança que falhou automaticamente antes de emitir um FAILED terminal.

Alterar o valor de um ciclo

Ajuste um ciclo individual (por exemplo, uma cobrança parcial) atualizando o seu schedule, referenciando tanto o ID da autorização quanto o ID do schedule:

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": 70
  }'

O novo amount (centavos) deve permanecer dentro da faixa minAmount/maxAmount da autorização. Referência: PUT .../pix-billing-automatic/{pixBillingAutomaticId}/schedules/{pixBillingAutomaticScheduleId}. Para listar e filtrar autorizações, use GET .../wallets/{walletId}/pix-billing-automatic.

Recorrer a boleto em caso de falhas repetidas

Quando os ciclos continuam falhando, 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,
    "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 é criado como INITIATED, e depois um webhook BOLETO_BILLING_UPDATED entrega o status: "CREATED" com o barcode e o digitableLine para apresentar ao cliente. Você também pode adicionar regras de desconto, multa e juros (txnDiscountAmount, txnFineAmount, txnInterestAmount) — veja 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 ciclo

Alterar o valor de um ciclo

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 ciclo

​Alterar o valor de um ciclo

​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 ciclo

Alterar o valor de um ciclo

Recorrer a boleto em caso de falhas repetidas

Próximos passos