> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cobrança recorrente com PIX Automático > Autorize um débito PIX recorrente, acompanhe cada ciclo e recorra ao boleto quando necessário 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 ```mermaid theme={null} sequenceDiagram participant You participant P3 as Portão 3 participant User participant Bank You->>P3: POST /pix-billing-automatic P3->>You: 200 with paymentUrl You->>User: Redirect to paymentUrl User->>Bank: Approve the authorization Bank->>P3: Authorization approved P3->>You: Webhook PIX_BILLING_AUTOMATIC_SCHEDULED loop Each cycle P3->>Bank: Request the scheduled charge Bank->>P3: Paid P3->>You: Webhook PIX_BILLING_AUTOMATIC_SCHEDULE_PAID end ``` ## Etapa 1: Criar a autorização ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-billing-automatic' \ -H 'Authorization: Bearer ' \ -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](/guides/wallets#register-a-pix-key). | | `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: ```json theme={null} { "_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`](/api-reference/banking/pix-automatic/realms-organizations-accounts-wallets-pix-billing-automatic-1) ## 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. | ```json theme={null} { "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. | ```json theme={null} { "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: ```bash theme={null} 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 ' \ -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}`](/api-reference/banking/pix-automatic/realms-organizations-accounts-wallets-pix-billing-automatic-schedules-2). Para listar e filtrar autorizações, use [`GET .../wallets/{walletId}/pix-billing-automatic`](/api-reference/banking/pix-automatic/realms-organizations-accounts-wallets-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: ```mermaid theme={null} sequenceDiagram participant You participant P3 as Portão 3 participant Bank loop Cycle Bank->>P3: Charge failed (after retries) P3->>You: Webhook PIX_BILLING_AUTOMATIC_SCHEDULE_FAILED end You->>P3: POST /boleto-billing P3->>You: 200 INITIATED P3->>You: Webhook BOLETO_BILLING_UPDATED (status CREATED) ``` ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto-billing' \ -H 'Authorization: Bearer ' \ -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`](/api-reference/banking/boleto-charges/realms-organizations-accounts-wallets-boleto-billing-1) ## Próximos passos Envelope de entrega e o catálogo completo de eventos. Cobranças PIX avulsas com QR Code.