> ## 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. # Recurring billing with Pix Automático > Authorize a recurring PIX debit, track each cycle, and fall back to boleto Pix Automático lets a customer authorize a recurring debit once, after which Portão 3 collects each cycle automatically. You create an authorization, send the customer to a hosted approval page, and then follow the lifecycle through webhooks. This guide also covers changing a cycle's amount and falling back to boleto when a charge fails. ## Flow ```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 ``` ## Step 1: Create the authorization ```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" } }' ``` | Field | Notes | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `pixDict` | The PIX key (DICT) that will receive the charges. See [Wallets for your customers](/guides/wallets#register-a-pix-key). | | `debitParty` | The paying customer. `type` is `INDIVIDUAL`; `document` is their CPF. | | `schedule.type` | Recurrence: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMESTER`, or `YEARLY`. | | `schedule.minAmount` / `maxAmount` | Centavos. The authorized range per cycle; set both equal for a fixed amount. | | `schedule.startDate` / `endDate` | The first and last cycle dates. | | `firstPayment` | Optional one-off charge collected up front (for example, a setup fee). | The response returns the authorization with a `paymentUrl` and the generated `schedules`: ```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" } ] } ``` Redirect the customer to `paymentUrl` to approve the authorization in their bank. Reference: [`POST .../wallets/{walletId}/pix-billing-automatic`](/api-reference/banking/pix-automatic/realms-organizations-accounts-wallets-pix-billing-automatic-1) ## Step 2: Follow the authorization lifecycle The `PIX_BILLING_AUTOMATIC_*` events track the authorization itself (the contract the customer approves): | Event | Meaning | | --------------------------------- | ----------------------------------------------------------------------- | | `PIX_BILLING_AUTOMATIC_CREATED` | You just created it. | | `PIX_BILLING_AUTOMATIC_INITIATED` | The customer opened their bank to review it. | | `PIX_BILLING_AUTOMATIC_SCHEDULED` | The customer approved the authorization. | | `PIX_BILLING_AUTOMATIC_EXPIRED` | The customer didn't approve in time — the link reactivates for a retry. | | `PIX_BILLING_AUTOMATIC_CANCELED` | You or the customer canceled it. | ```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" } } ``` ## Step 3: Follow each cycle The `PIX_BILLING_AUTOMATIC_SCHEDULE_*` events track the individual charges (one per cycle): | Event | Meaning | | ------------------------------------------------- | --------------------------------------- | | `PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE` | The cycle was created. | | `PIX_BILLING_AUTOMATIC_SCHEDULE_SCHEDULED` | The charge is scheduled at the bank. | | `PIX_BILLING_AUTOMATIC_SCHEDULE_PAID` | The cycle was paid. | | `PIX_BILLING_AUTOMATIC_SCHEDULE_FAILED` | The charge failed (after retries). | | `PIX_BILLING_AUTOMATIC_SCHEDULE_CANCELED` | You or the customer canceled the cycle. | ```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" } } ``` Portão 3 retries a failed charge automatically before emitting a terminal `FAILED`. ## Change a cycle's amount Adjust an individual cycle (for example, a partial charge) by updating its schedule, referencing both the authorization ID and the schedule ID: ```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 }' ``` The new `amount` (centavos) must stay within the authorization's `minAmount`/`maxAmount` range. Reference: [`PUT .../pix-billing-automatic/{pixBillingAutomaticId}/schedules/{pixBillingAutomaticScheduleId}`](/api-reference/banking/pix-automatic/realms-organizations-accounts-wallets-pix-billing-automatic-schedules-2). To list and filter authorizations, use [`GET .../wallets/{walletId}/pix-billing-automatic`](/api-reference/banking/pix-automatic/realms-organizations-accounts-wallets-pix-billing-automatic). ## Fall back to boleto on repeated failure When cycles keep failing, issue a boleto for the same amount so the customer can still pay: ```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" } } }' ``` The boleto is created `INITIATED`, then a `BOLETO_BILLING_UPDATED` webhook delivers `status: "CREATED"` with the `barcode` and `digitableLine` to present to the customer. You can also add discount, fine, and interest rules (`txnDiscountAmount`, `txnFineAmount`, `txnInterestAmount`) — see the endpoint reference for the full body. Reference: [`POST .../wallets/{walletId}/boleto-billing`](/api-reference/banking/boleto-charges/realms-organizations-accounts-wallets-boleto-billing-1) ## Next steps Delivery envelope and the full event catalog. One-off PIX charges with a QR Code.