Pix Automático

Pix Automático lets you charge your customers on a recurring basis (subscriptions, monthly fees, services) without the payer authorizing each charge. The customer authorizes the recurrence once, in their own bank’s application, and from then on each charge is debited automatically on the agreed date, within the limits that were authorized. This guide covers the full cycle: creating the recurrence, managing collections, cancelling, reading the objects back and the webhooks fired at each step.

Concepts

On Trio, Pix Automático is made of three chained objects:

Recurrence (recurrence): the authorization contract between you and the payer. It defines periodicity, amount (fixed or variable), dates and retry rules.
Collection (collection): each charge generated from the recurrence, for example October’s monthly fee.
Attempt (attempt): each try to settle a collection. The same collection can have more than one attempt, according to the retry policy.

All examples use the sandbox base URL https://api.sandbox.trio.com.br. In production, switch the base URL to https://api.trio.com.br.

Endpoints

Action	Method	Endpoint
Create recurrence	`POST`	`/v2/in/pix/recurrences`
List recurrences	`GET`	`/v2/in/pix/recurrences`
Get recurrence	`GET`	`/v2/in/pix/recurrences/{id}`
Cancel recurrence	`POST`	`/v2/in/pix/recurrences/{id}/cancel`
Get authorization request	`GET`	`/v2/in/pix/recurrences/requests/{id}`
List collections	`GET`	`/v2/in/pix/recurrences/collections`
Get collection	`GET`	`/v2/in/pix/recurrences/collections/{id}`
Create next collection (manual management)	`POST`	`/v2/in/pix/recurrences/collections/next`
Update collection amount	`PUT`	`/v2/in/pix/recurrences/collections/{id}`
Schedule collection (manual management)	`POST`	`/v2/in/pix/recurrences/collections/{id}/schedule`
Cancel collection	`POST`	`/v2/in/pix/recurrences/collections/{id}/cancel`
List attempts	`GET`	`/v2/in/pix/recurrences/collections/attempts`
Get attempt	`GET`	`/v2/in/pix/recurrences/collections/attempts/{id}`

Create a recurrence

Send a POST to Create recurrence. The fields below apply to every journey; the journey variations come next.

POST /v2/in/pix/recurrences

Field	Required	Description
`bank_account_id`	Yes	Bank account that receives the collections.
`counterparty`	Yes	The payer’s data: `tax_number` and `name` are required. For authorization through the application (`app` journey), `counterparty.bank_account` is also required.
`description`	Yes	Description of the recurrence, at most 35 characters. It is shown to the payer during authorization.
`periodicity`	Yes	How often the collection happens. See the values below.
`contract_number`	Yes	The contract or subscription number in your system, at most 35 characters.
`start_date`	Yes	First day of the recurrence (ISO 8601 date, `YYYY-MM-DD`).
`end_date`	No	Last day of the recurrence (`YYYY-MM-DD`). When omitted, the recurrence has no end date.
`external_id`	No	Your internal reference for the recurrence.
`amounts`	No	Fixed amount or minimum amount of each collection. When omitted, the recurrence has a variable amount and no minimum. See Fixed and variable amounts.
`first_payment`	No	A first payment combined with the authorization. See Authorization journeys.
`options`	No	Settings of the recurrence. See Options.

start_date must be at least 3 days after the current date. Possible values of periodicity:

Value	Meaning
`week`	Every week
`mnth`	Every month
`qurt`	Every 3 months
`mian`	Every 6 months
`year`	Every year

Fixed and variable amounts

The amounts block defines how the amount of each collection is determined:

Fixed amount: send amounts.fixed in cents (BRL 100.00 = 10000). Every collection has this amount and you cannot change it before it is sent.
Variable amount with a minimum: send amounts.minimum in cents. The payer cannot authorize a limit lower than the minimum, and you must inform the amount of each collection before its collection date.
Variable amount with no minimum: omit amounts. You must also inform the amount before each collection.

On variable-amount recurrences, informing the amount before the collection is sent is mandatory. Either update the amount of the collection or send amount when you schedule it.

Authorization journeys

Pix Automático defines different authorization journeys. On Trio, the journey results from the combination of three parameters:

options.authorization_type: qrcode generates a QR code for the payer to authorize; app sends the authorization request straight to the payer’s bank application.
first_payment: present or absent, defines whether a first payment is combined with the authorization.
first_payment.recurrence_required: true approves the recurrence and the first payment in a single authorization; false lets the payer pay the first payment and still refuse the recurrence.

The reference.type field in the response indicates the channel used: qrdn (dynamic QR code), qres (static QR code) or requ (request sent to the application). The four journeys below are the ones our customers use most.

Journey A: QR code, fixed amount, no first payment

The customer scans a QR code and authorizes the recurrence. No charge happens at authorization time.

{
  "bank_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
  "counterparty": {
    "tax_number": "70004764005",
    "name": "Jhon Doe"
  },
  "description": "Monthly subscription",
  "contract_number": "CONTRACT-2025-001",
  "periodicity": "mnth",
  "start_date": "2025-11-01",
  "amounts": {
    "fixed": 4990
  },
  "options": {
    "authorization_type": "qrcode"
  }
}

Journey B: QR code with a first payment

The payer approves the recurrence and the first charge in a single action. Use it when the subscription starts with an immediate charge. due_detail configures the due date, interest, fine and discounts of the first payment.

{
  "bank_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
  "counterparty": {
    "tax_number": "70004764005",
    "name": "Jhon Doe"
  },
  "description": "Monthly subscription",
  "contract_number": "CONTRACT-2025-002",
  "periodicity": "mnth",
  "start_date": "2025-11-01",
  "amounts": {
    "fixed": 4990
  },
  "first_payment": {
    "amount": 4990,
    "dict_key": "pix-key-of-your-bank-account",
    "recurrence_required": true,
    "due_detail": {
      "due_date": "2025-10-25",
      "fine": {
        "calculation_type": "percentage",
        "value": 200
      },
      "interest": {
        "calculation_type": "percentage",
        "value": 100,
        "calculation_period": "month",
        "calculation_days": "calendar"
      },
      "discount": {
        "per_day_antecipated": {
          "calculation_type": "amount",
          "amount": 50,
          "calculation_days": "working"
        }
      }
    }
  },
  "options": {
    "authorization_type": "qrcode",
    "qrcode_expiration_seconds": 86400
  }
}

Every rule inside due_detail carries a calculation_type: with amount, send amount in cents; with percentage, send value in basis points (100 = 1%). Only due_date is required.

Rule	Description
`fine`	Fine charged after the due date.
`interest`	Interest charged after the due date. `calculation_period` (`day`, `month`, `year`) and `calculation_days` (`calendar`, `working`) define how it accrues.
`discount.per_day_antecipated`	Discount per day paid in advance (`calculation_days`: `calendar` or `working`).
`discount.fixed_until_due`	Discount granted until each date listed in `amounts[]`, each entry carrying `date` and either `amount` or `value`. Set only one of the two discount options.
`rebate`	Rebate applied to the amount.

These are the same payment rules a boleto uses; the Create a boleto guide explains them in detail. With recurrence_required: false, the payer can pay the first payment and still refuse the recurrence; with true, both are approved together in a single authorization.

Journey C: request sent to the payer’s app

Instead of generating a QR code, Trio sends the authorization request directly to the payer’s bank application. counterparty.bank_account is required: it is the account that receives the approval request.

{
  "bank_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
  "counterparty": {
    "tax_number": "70004764005",
    "name": "Jhon Doe",
    "bank_account": {
      "ispb": "49931906",
      "branch": "0001",
      "number": "12345678",
      "digit": "9"
    }
  },
  "description": "Annual plan",
  "contract_number": "CONTRACT-2025-003",
  "periodicity": "year",
  "start_date": "2025-11-01",
  "amounts": {
    "fixed": 59900
  },
  "options": {
    "authorization_type": "app"
  }
}

When the authorization goes through the application, Trio creates an authorization request (recurrence request). Follow it with load_requests when you read the recurrence, or with GET /v2/in/pix/recurrences/requests/{id}. The request carries the recurrence.id it belongs to, the counterparty it was sent to and expires_at, the moment after which the payer can no longer answer it. Its statuses are created, sent, received, rejected, accepted, expired and cancelled.

Journey D: variable amount with a minimum

For subscriptions whose amount changes every cycle (consumption, usage, variable installments), send only the minimum. You must inform the amount of each collection before it is sent.

{
  "bank_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
  "counterparty": {
    "tax_number": "70004764005",
    "name": "Jhon Doe"
  },
  "description": "Consumption bill",
  "contract_number": "CONTRACT-2025-004",
  "periodicity": "mnth",
  "start_date": "2025-11-01",
  "amounts": {
    "minimum": 1000
  },
  "options": {
    "authorization_type": "qrcode",
    "automatic_schedule": false,
    "automated_attempt_retry": true
  }
}

Response

On success you receive 201 Created with the recurrence object. id is the recurrence identifier on Trio. For QR code journeys, the qrcode block carries the hash (the BR code, the Pix copy-and-paste code) and the id of the QR code; it is null when the journey has no QR code. Amounts come back as money objects ({ "amount", "currency" }), the settings are grouped under options, the payer under counterparty and the authorization channel under reference.

{
  "data": {
    "id": "0199d478-de39-fcf3-87a9-e8bded7db468",
    "type": "in",
    "status": "created",
    "description": "Monthly subscription",
    "contract_number": "CONTRACT-2025-001",
    "external_id": null,
    "periodicity": "mnth",
    "start_date": "2025-11-01",
    "end_date": null,
    "amounts": {
      "fixed": { "amount": 4990, "currency": "BRL" },
      "minimum": null,
      "maximum": null
    },
    "first_payment": {
      "amount": null,
      "date": "2025-11-01"
    },
    "number_of_collections": null,
    "authorized_at": null,
    "options": {
      "automatic_schedule": true,
      "retry_policy": "3r_7d",
      "next_working_day": false
    },
    "bank_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
    "counterparty": {
      "id": "49521ece-9203-186b-cfc7-281c207f7f52",
      "bank_account": { "id": null }
    },
    "reference": {
      "id": null,
      "type": "qrdn"
    },
    "origin": {
      "id": "019f4198-9de7-4ba7-d718-5e9fce7cbccb",
      "type": "api_client"
    },
    "qrcode": {
      "id": "0199d478-de3a-7c1e-9b2f-4e5d6a7b8c9d",
      "type": "dynamic",
      "hash": "00020101021226630014br.gov.bcb.pix...6304B527"
    },
    "inserted_at": "2025-10-11T18:11:55.070544Z",
    "updated_at": "2025-10-11T18:11:55.070544Z"
  }
}

Offer the hash to the payer as copy and paste, or render the QR code image from it. The recurrence only takes effect after the payer authorizes it, when authorized_at is filled in. Follow that through the recurrence.approved webhook, or recurrence.rejected and recurrence.expired.

Options

The options block defines how the recurrence behaves over time. All fields are optional and have default values.

Field	Default	Description
`authorization_type`	`qrcode`	`qrcode` generates a QR code; `app` sends the request directly to the payer’s application (requires `counterparty.bank_account`).
`automatic_schedule`	`true`	Automatic management of collections. When `false`, you create and schedule each collection manually.
`automated_attempt_retry`	`true`	Who manages the retries when a payment fails. When `true`, Trio manages them automatically; when `false`, your application does.
`retry_policy`	`3r_7d`	Retry policy when a collection fails. `3r_7d`: 3 retries over 7 days, on alternating days. `none`: no retries.
`next_working_day`	`false`	When `true`, no collection happens on holidays; the collection moves to the payer’s next working day.
`qrcode_expiration_seconds`	`86400`	Expiration time, in seconds, of the dynamic QR code. Ignored for static QR codes.

Automatic and manual collection management

With automatic_schedule: true (the default), Trio creates and schedules each collection at the defined periodicity. You do nothing each cycle, just react to the webhooks. Use this mode when the amount is fixed or you can determine it in advance. With automatic_schedule: false (manual management), you create and schedule each collection every cycle. Use this mode when, for example, the variable amount is only known close to the collection date. See Manage collections.

Retries and non-payment

retry_policy defines what happens when a collection is not settled, and automated_attempt_retry defines who runs the retries: with true, Trio creates and manages them; with false, your application does.

3r_7d: the collection is retried 3 times over 7 days, on alternating days. Each retry generates a new attempt. If no attempt is settled, the collection moves to a final failure or expiration status.
none: no retries. A failed attempt ends the collection.

The retry policy works at the collection level, not the recurrence level. If your business rule is to end the subscription after an unpaid collection, monitor the attempt events (recurrence_collection_attempt with type failed or expired) or the collection events (recurrence_collection with type expired or rejected). When you detect that the retries are exhausted, cancel the recurrence to implement automatic cancellation for non-payment.

Manage collections

Each collection is one debit occurrence of the recurrence. A collection goes through the statuses created, active, settled, expired, rejected and cancelled. Its attempts go through requested, scheduled, settled, cancelled, rejected, expired and failed.

Create the next collection

With automatic_schedule: false, create the next collection of the recurrence with Create next collection. recurrence_id (required) is the recurrence the collection belongs to.

POST /v2/in/pix/recurrences/collections/next

{
  "recurrence_id": "0199d478-de39-fcf3-87a9-e8bded7db468"
}

The 201 Created response brings the collection with its stages and attempts. The collection points to its recurrence through recurrence.id, and each stage records a status change, with error_code and error_message when there is a rejection reason.

{
  "data": {
    "id": "019a0d9e-d21f-0bf6-36be-abb0e6be5792",
    "status": "created",
    "amount": { "amount": 1000, "currency": "BRL" },
    "additional_info": null,
    "bank_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
    "recurrence": { "id": "0199d478-de39-fcf3-87a9-e8bded7db468" },
    "next_working_day": false,
    "final_date": null,
    "transaction_date": null,
    "stages": [
      {
        "id": "019a0d9e-d21f-5a1e-0c1d-9e5f2b8a7c31",
        "status": "created",
        "error_code": null,
        "error_message": null,
        "inserted_at": "2025-10-22T20:31:43.647903Z"
      }
    ],
    "attempts": [
      {
        "id": "019809e6-c836-fe49-0b1a-ccd48befb6b8",
        "status": "requested",
        "due_date": "2025-11-01",
        "external_id": null,
        "end_to_end_id": "E33333333202511011500duiiTl1rnpc",
        "transaction_date": null,
        "inserted_at": "2025-10-22T20:31:43.647903Z",
        "updated_at": "2025-10-22T20:31:43.647903Z"
      }
    ],
    "inserted_at": "2025-10-22T20:31:43.647903Z",
    "updated_at": "2025-10-22T20:31:43.647903Z"
  }
}

Schedule a collection

Once created, schedule the collection so Trio sends it to the payer’s bank. Scheduling must happen between 2 and 10 days before the cycle’s payment date. Call Schedule collection:

POST /v2/in/pix/recurrences/collections/{id}/schedule

{
  "amount": 12990,
  "due_date": "2025-11-01",
  "external_id": "COBR-2025-11"
}

Field	Required	Description
`amount`	No	Amount in cents. Use it to inform or update the amount before scheduling. It does not work on fixed-amount recurrences.
`due_date`	No	Day the attempt is due (`YYYY-MM-DD`).
`external_id`	No	Your reference for the attempt.

The success response is 204 No Content. Follow the result through the recurrence_collection_attempt event with type scheduled and, later, settled or failed.

Update the amount of a collection

On variable-amount recurrences, you can update the amount of a collection that has not yet been sent to the payer’s bank with Update collection amount:

PUT /v2/in/pix/recurrences/collections/{id}

{
  "amount": 13500
}

amount is the new amount in cents. The update is only possible while the collection has not been sent; on fixed-amount recurrences the amount cannot be changed. The success response is 204 No Content. Read the collection back with GET /v2/in/pix/recurrences/collections/{id} to confirm the new amount.

Cancel a collection

Cancel one collection, without cancelling the whole recurrence, with Cancel collection:

POST /v2/in/pix/recurrences/collections/{id}/cancel

{
  "requester_tax_number": "12345678000190",
  "entity_id": "019953ad-1738-b094-097c-7941a0c642a5"
}

Field	Required	Description
`requester_tax_number`	Yes	CPF or CNPJ of whoever requests the cancellation.
`entity_id`	No	Entity identifier.

The success response is 204 No Content. The collection moves to cancelled, you receive the recurrence_collection.cancelled event and can confirm it with a GET. The next collections of the recurrence continue normally.

Cancel a recurrence

To end the recurrence completely, so that no future collection is generated, call Cancel recurrence:

POST /v2/in/pix/recurrences/{id}/cancel

{
  "requester_tax_number": "12345678000190"
}

requester_tax_number (required) is the CPF or CNPJ of whoever requests the cancellation. The success response is 204 No Content. The recurrence moves to cancelled and you receive the recurrence.cancelled event.

Read recurrences, collections and attempts

The GET endpoints return the current state of each object. Listings are paginated with limit, before and after; see Pagination.

Get a recurrence

Call Get recurrence:

GET /v2/in/pix/recurrences/{id}

Parameter	Required	Description
`load_stages`	No	`true` includes the recurrence’s stage history.
`load_requests`	No	`true` includes the authorization requests (`app` journey).
`entity_id`, `group_id`, `bank_account_id`	No	Optional filters.

List recurrences

Call List recurrences:

GET /v2/in/pix/recurrences

Parameter	Required	Description
`from_datetime`, `to_datetime`	Yes	Time window.
`bank_account_id`, `entity_id`	No	Optional filters.
`limit`, `before`, `after`	No	Pagination.

Get an authorization request

Call Get authorization request. load_stages includes the request’s stages; entity_id, group_id and bank_account_id are optional filters.

GET /v2/in/pix/recurrences/requests/{id}

Get a collection

Call Get collection to read one collection with its stages and attempts:

GET /v2/in/pix/recurrences/collections/{id}

Parameter	Required	Description
`load_stages`, `load_attempts`	No	Include the stages and the attempts.
`entity_id`, `group_id`, `bank_account_id`	No	Optional filters.

List collections

Call List collections to list the collections of a recurrence:

GET /v2/in/pix/recurrences/collections

Parameter	Required	Description
`recurrence_id`	Yes	Recurrence whose collections are listed.
`from_datetime`, `to_datetime`	Yes	Time window.
`entity_id`	No	Optional filter.
`limit`, `before`, `after`	No	Pagination.

List attempts

Call List attempts to list the attempts of a collection:

GET /v2/in/pix/recurrences/collections/attempts

Parameter	Required	Description
`recurrence_id`, `collection_id`	Yes	Recurrence and collection whose attempts are listed.
`entity_id`, `from_datetime`, `to_datetime`	No	Optional filters.
`limit`, `before`, `after`	No	Pagination.

Get an attempt

Call Get attempt. load_stages includes the attempt’s stages; entity_id is an optional filter.

GET /v2/in/pix/recurrences/collections/attempts/{id}

Each attempt carries the collection.id it charges, its due_date, the Pix end_to_end_id and the transaction_date once it is paid.

Webhooks

Trio notifies each step asynchronously through webhooks. Three event categories relate to Pix Automático; the Events catalog describes the payload structure.

Recurrence events

Category recurrence, fired on the state changes of the recurrence (the authorization contract).

Type	Meaning
`created`	The recurrence was created.
`approved`	The recurrence was approved by the payer.
`rejected`	The recurrence was rejected.
`expired`	The recurrence expired (authorization not completed in time).
`cancelled`	The recurrence was cancelled.

Payload example

Collection events

Category recurrence_collection, fired on the state changes of each collection.

Type	Meaning
`created`	The collection was created.
`active`	The collection became active (scheduled or sent to the payer’s bank).
`settled`	The collection was settled.
`expired`	The collection expired.
`rejected`	The collection was rejected.
`cancelled`	The collection was cancelled.

Payload example

Attempt events

Category recurrence_collection_attempt, fired on each attempt to settle a collection. This is where you follow the actual result of the debit and the retries.

Type	Meaning
`requested`	An attempt was created.
`scheduled`	The attempt was scheduled.
`settled`	The attempt was settled (payment completed).
`cancelled`	The attempt was cancelled.
`rejected`	The attempt was rejected.
`expired`	The attempt expired.
`failed`	The attempt failed.

Payload example

End-to-end summary

The table ties each step of the process to the corresponding endpoint and webhook.

Step	What you do	Expected webhook
1. Create recurrence	`POST /v2/in/pix/recurrences` and deliver the QR code or send the request to the application	`recurrence.created`
2. Payer authorization	Nothing (payer’s action)	`recurrence.approved` · `recurrence.rejected` · `recurrence.expired`
3a. Automatic collection	Nothing (automatic management)	`recurrence_collection.created` → `active`
3b. Manual collection	`POST .../collections/next` + `POST .../collections/{id}/schedule` (with `amount` and `due_date` if variable)	`recurrence_collection.created` → `active`
4. Amount adjustment (variable)	`PUT /v2/in/pix/recurrences/collections/{id}` before it is sent	—
5. Settlement	Nothing (processing)	`recurrence_collection_attempt.scheduled` → `settled`
6. Failure or non-payment	React according to `retry_policy`	`recurrence_collection_attempt.failed` · `recurrence_collection.expired`
7. Cancel collection	`POST /v2/in/pix/recurrences/collections/{id}/cancel`	`recurrence_collection.cancelled`
8. Cancel recurrence	`POST /v2/in/pix/recurrences/{id}/cancel`	`recurrence.cancelled`

Handle the final states (settled, failed, expired, cancelled) through webhooks and use the GET endpoints for reconciliation. For non-payment, combine attempt monitoring with the retry_policy and decide, in your application, whether to cancel the recurrence.

Next steps

Creating your first webhook: receive the recurrence, collection and attempt events.
QR code types: the QR code the payer scans to authorize a recurrence.
Create a boleto: the fine, interest and discount rules in detail.
Receivables overview: all cash-in guides.

Onboarding

Receivables

Payments

Operations

Trio MCP

Trio SDK

Concepts

Endpoints

Create a recurrence

Fixed and variable amounts

Authorization journeys

Journey A: QR code, fixed amount, no first payment

Journey B: QR code with a first payment

Journey C: request sent to the payer’s app

Journey D: variable amount with a minimum

Response

Options

Automatic and manual collection management

Retries and non-payment

Manage collections

Create the next collection

Schedule a collection

Update the amount of a collection

Cancel a collection

Cancel a recurrence

Read recurrences, collections and attempts

Get a recurrence

List recurrences

Get an authorization request

Get a collection

List collections

List attempts

Get an attempt

Webhooks

Recurrence events

Collection events

Attempt events

End-to-end summary

Next steps

​Concepts

​Endpoints

​Create a recurrence

​Fixed and variable amounts

​Authorization journeys

​Journey A: QR code, fixed amount, no first payment

​Journey B: QR code with a first payment

​Journey C: request sent to the payer’s app

​Journey D: variable amount with a minimum

​Response

​Options

​Automatic and manual collection management

​Retries and non-payment

​Manage collections

​Create the next collection

​Schedule a collection

​Update the amount of a collection

​Cancel a collection

​Cancel a recurrence

​Read recurrences, collections and attempts

​Get a recurrence

​List recurrences

​Get an authorization request

​Get a collection

​List collections

​List attempts

​Get an attempt

​Webhooks

​Recurrence events

​Collection events

​Attempt events

​End-to-end summary

​Next steps

Concepts

Endpoints

Create a recurrence

Fixed and variable amounts

Authorization journeys

Journey A: QR code, fixed amount, no first payment

Journey B: QR code with a first payment

Journey C: request sent to the payer’s app

Journey D: variable amount with a minimum

Response

Options

Automatic and manual collection management

Retries and non-payment

Manage collections

Create the next collection

Schedule a collection

Update the amount of a collection

Cancel a collection

Cancel a recurrence

Read recurrences, collections and attempts

Get a recurrence

List recurrences

Get an authorization request

Get a collection

List collections

List attempts

Get an attempt

Webhooks

Recurrence events

Collection events

Attempt events

End-to-end summary

Next steps