Recurring billing with Pix Automático

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

Step 1: Create the authorization

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

Field	Notes
`pixDict`	The PIX key (DICT) that will receive the charges. See Wallets for your customers.
`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:

{
  "_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

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.

{
  "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.

{
  "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:

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
  }'

The new amount (centavos) must stay within the authorization’s minAmount/maxAmount range. Reference: PUT .../pix-billing-automatic/{pixBillingAutomaticId}/schedules/{pixBillingAutomaticScheduleId}. To list and filter authorizations, use GET .../wallets/{walletId}/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:

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

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

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Recurring billing with Pix Automático

Flow

Step 1: Create the authorization

Step 2: Follow the authorization lifecycle

Step 3: Follow each cycle

Change a cycle’s amount

Fall back to boleto on repeated failure

Next steps

Receive webhooks

Charge with PIX

​Flow

​Step 1: Create the authorization

​Step 2: Follow the authorization lifecycle

​Step 3: Follow each cycle

​Change a cycle’s amount

​Fall back to boleto on repeated failure

​Next steps

Receive webhooks

Charge with PIX

Flow

Step 1: Create the authorization

Step 2: Follow the authorization lifecycle

Step 3: Follow each cycle

Change a cycle’s amount

Fall back to boleto on repeated failure

Next steps