Recurring billing with Pix Automático

Pix Automático lets a customer authorize a recurring debit once, in their own bank, after which Portão 3 collects each charge automatically. You create an authorization, send the customer to its approval page, and then follow the authorization and its charges through webhooks or by reading them back. This guide also covers changing a charge’s amount, canceling, 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": "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"
    }
  }'

Field	Notes
`pixDict`	One of the wallet’s active PIX keys, as registered: the charges are paid to it. See Wallets for your customers.
`debitParty`	The paying customer. `type` is `INDIVIDUAL` with their CPF in `document`, or `BUSINESS` with the company’s CNPJ.
`schedule.type`	Recurrence: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMESTER`, or `YEARLY`.
`schedule.minAmount` / `maxAmount`	Centavos. The range the customer authorizes per charge; each recurring charge is created with `minAmount`. Set both equal for a fixed amount.
`schedule.startDate` / `endDate`	Required. The date of the first recurring charge — at least two days from today, and after `firstPayment.date` — and the last day a charge can fall on.
`schedule.dates`	Optional. Explicit charge dates, from `startDate` to `endDate`; without it (or with an empty list), a charge falls on `startDate` and then at every interval up to `endDate`.
`firstPayment`	Optional one-off charge, collected on its `date` once the customer approves (for example, a setup fee): today or later, before `schedule.startDate`.
`callBackUrlForPaymentProvider`	Optional. Your own pages the customer returns to (`success`, `pending`, `error`) after the approval page.

The response is 201 Created: the authorization, status CREATED, with the paymentUrl and every charge in schedules — the first payment (isFirstPayment: true) and each recurring charge, all 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" }
  ]
}

The authorization keeps its own dates: schedule.startDate is two days before the schedule.startDate you sent — or the day after the first payment, when that is later — and schedule.endDate the day after the one you sent. 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 consent the customer approves):

Event	Meaning
`PIX_BILLING_AUTOMATIC_CREATED`	You just created it (`CREATED`).
`PIX_BILLING_AUTOMATIC_INITIATED`	The customer started the approval in their bank (`INITIATED`).
`PIX_BILLING_AUTOMATIC_SCHEDULED`	The customer approved the authorization (`SCHEDULED`); the first payment, if any, is charged on its date.
`PIX_BILLING_AUTOMATIC_EXPIRED`	The customer didn’t approve before the first charges were due (`EXPIRED`); its pending charges expire too.
`PIX_BILLING_AUTOMATIC_CANCELED`	You canceled it (`CANCELED`).

When the customer revokes the authorization in their bank, it moves to REVOKED and its pending charges are canceled; that change has no webhook, so read the authorization back.

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

To read it at any time, with all its charges, use GET .../pix-billing-automatic/{pixBillingAutomaticId}.

Step 3: Follow each charge

The PIX_BILLING_AUTOMATIC_SCHEDULE_* events track the individual charges:

Event	Meaning
`PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE`	The charge is about to be sent to the customer’s bank (it is sent 2 to 10 days before its date).
`PIX_BILLING_AUTOMATIC_SCHEDULE_SCHEDULED`	The charge is scheduled at the customer’s bank (`SCHEDULED`).
`PIX_BILLING_AUTOMATIC_SCHEDULE_PAID`	The charge was paid (`PAID`).
`PIX_BILLING_AUTOMATIC_SCHEDULE_FAILED`	The charge failed and won’t be tried again (`FAILED`); `error` says why.
`PIX_BILLING_AUTOMATIC_SCHEDULE_CANCELED`	The charge was canceled at the customer’s bank (`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"
  }
}

When the customer’s bank can’t debit a charge, Portão 3 asks for a new attempt a day or two later — up to three attempts in all, counting the one on the due date, each listed in the charge’s attempts — unless the refusal is final (for example, the customer’s limit for the period was reached). Then the charge becomes FAILED. A charge the customer’s bank refuses to schedule has no webhook: it ends as SCHEDULE_ERROR, or stays CREATED past its date with no external.scheduleId and a SCHEDULE_ATTEMPT_FAILED event in its history. If you rely on webhooks, also check the wallet’s charges for status=SCHEDULE_ERROR (treat it like FAILED) and for status=CREATED with a past maxDueDate. Such a CREATED charge was most likely refused — but in rare cases the customer’s bank accepted it and the confirmation was lost, so confirm with Portão 3 support before charging it another way. A charge CREATED past its date that does carry external.scheduleId is still being processed by the customer’s bank: wait for its outcome — don’t charge it another way. To see what is due and what was paid across all the wallet’s authorizations, use GET .../wallets/{walletId}/pix-billing-automatic/schedules, filtered by status and due date. The events of an authorization — its creation and cancellations, each update from the customer’s bank, with its error — are in GET .../pix-billing-automatic/{pixBillingAutomaticId}/history.

Change a charge’s amount

Adjust an individual charge (for example, a partial charge) by updating it, referencing both the authorization ID and the charge 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": 35000
  }'

The new amount (centavos) must stay within the authorization’s minAmount/maxAmount range, so plan a variable range when you create the authorization if you’ll need it. Only a recurring charge that hasn’t been sent to the customer’s bank yet (CREATED) can change; the first payment can’t, it goes with the authorization. Reference: PUT .../pix-billing-automatic/{pixBillingAutomaticId}/schedules/{pixBillingAutomaticScheduleId}. To list and filter authorizations, use GET .../wallets/{walletId}/pix-billing-automatic.

Cancel

One charge — POST .../schedules/{pixBillingAutomaticScheduleId}/cancel cancels it and keeps the authorization and its other charges. The first payment can’t be canceled on its own before the customer approves: cancel the whole authorization instead.
The whole authorization — POST .../pix-billing-automatic/{pixBillingAutomaticId}/cancel stops it: no further charge is made, and its charges still CREATED or SCHEDULED are canceled.

A charge already sent to the customer’s bank can’t be canceled on or after its date. Both answer 204 No Content.

Fall back to boleto on repeated failure

When charges keep failing (FAILED or SCHEDULE_ERROR), 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,
    "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"
      }
    }
  }'

The boleto comes back CREATED, with the digitableLine and barcode to present to the customer — or download its PDF with GET .../boleto-billing/{boletoId}/download/pdf. Rarely it comes back INITIATED, without them yet: read it back until it is CREATED. There is no webhook for a boleto charge, so read it back with GET .../boleto-billing/{boletoId} to know when it is PAID. You can also add discount, fine, and interest rules (txnDiscountAmount, txnFineAmount, txnInterestAmount) — see Charge with a boleto and 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 charge

Change a charge’s amount

Cancel

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 charge

​Change a charge’s amount

​Cancel

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

Change a charge’s amount

Cancel

Fall back to boleto on repeated failure

Next steps