> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Pix Automático

> Create recurrences, manage collections and attempts, and follow each step through webhooks with the API.

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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/generate-recurrence.md) | `POST` | `/v2/in/pix/recurrences` |
| [List recurrences](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/list-recurrences.md) | `GET` | `/v2/in/pix/recurrences` |
| [Get recurrence](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-recurrence.md) | `GET` | `/v2/in/pix/recurrences/{id}` |
| [Cancel recurrence](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/cancel-recurrence.md) | `POST` | `/v2/in/pix/recurrences/{id}/cancel` |
| [Get authorization request](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-recurrence-request.md) | `GET` | `/v2/in/pix/recurrences/requests/{id}` |
| [List collections](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/list-recurrence-collections.md) | `GET` | `/v2/in/pix/recurrences/collections` |
| [Get collection](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-collection.md) | `GET` | `/v2/in/pix/recurrences/collections/{id}` |
| [Create next collection](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/create-next-collection.md) (manual management) | `POST` | `/v2/in/pix/recurrences/collections/next` |
| [Update collection amount](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/update-collection.md) | `PUT` | `/v2/in/pix/recurrences/collections/{id}` |
| [Schedule collection](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/schedule-collection.md) (manual management) | `POST` | `/v2/in/pix/recurrences/collections/{id}/schedule` |
| [Cancel collection](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/cancel-collection.md) | `POST` | `/v2/in/pix/recurrences/collections/{id}/cancel` |
| [List attempts](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/list-collection-attempts.md) | `GET` | `/v2/in/pix/recurrences/collections/attempts` |
| [Get attempt](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-collection-attempt.md) | `GET` | `/v2/in/pix/recurrences/collections/attempts/{id}` |

## Create a recurrence

Send a `POST` to [Create recurrence](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/generate-recurrence.md). The fields below apply to every journey; the journey variations come next.

```http theme={null}
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](#fixed-and-variable-amounts). |
| `first_payment` | No | A first payment combined with the authorization. See [Authorization journeys](#authorization-journeys). |
| `options` | No | Settings of the recurrence. See [Options](#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](#update-the-amount-of-a-collection) or send `amount` when you [schedule it](#schedule-a-collection).

### 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md) 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.

```json theme={null}
{
  "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}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-recurrence-request). 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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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](#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.

> [!NOTE]
>
> 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](#cancel-a-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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/create-next-collection.md). `recurrence_id` (required) is the recurrence the collection belongs to.

```http theme={null}
POST /v2/in/pix/recurrences/collections/next
```

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/schedule-collection.md):

```http theme={null}
POST /v2/in/pix/recurrences/collections/{id}/schedule
```

```json theme={null}
{
  "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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/update-collection.md):

```http theme={null}
PUT /v2/in/pix/recurrences/collections/{id}
```

```json theme={null}
{
  "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}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-collection) to confirm the new `amount`.

### Cancel a collection

Cancel one collection, without cancelling the whole recurrence, with [Cancel collection](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/cancel-collection.md):

```http theme={null}
POST /v2/in/pix/recurrences/collections/{id}/cancel
```

```json theme={null}
{
  "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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/cancel-recurrence.md):

```http theme={null}
POST /v2/in/pix/recurrences/{id}/cancel
```

```json theme={null}
{
  "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](https://docs.trio.com.br/v2/developers/pagination.md).

### Get a recurrence

Call [Get recurrence](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-recurrence.md):

```http theme={null}
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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/list-recurrences.md):

```http theme={null}
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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-recurrence-request.md). `load_stages` includes the request's stages; `entity_id`, `group_id` and `bank_account_id` are optional filters.

```http theme={null}
GET /v2/in/pix/recurrences/requests/{id}
```

### Get a collection

Call [Get collection](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-collection.md) to read one collection with its stages and attempts:

```http theme={null}
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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/list-recurrence-collections.md) to list the collections of a recurrence:

```http theme={null}
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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/list-collection-attempts.md) to list the attempts of a collection:

```http theme={null}
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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/recurrences/get-collection-attempt.md). `load_stages` includes the attempt's stages; `entity_id` is an optional filter.

```http theme={null}
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](https://docs.trio.com.br/v2/webhooks/events/overview.md) 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](https://docs.trio.com.br/v2/webhooks/events/overview.md)

### 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](https://docs.trio.com.br/v2/webhooks/events/overview.md)

### 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](https://docs.trio.com.br/v2/webhooks/events/overview.md)

## 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` |

> [!TIP]
>
> 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](https://docs.trio.com.br/v2/guides/creating-your-first-webhook.md): receive the recurrence, collection and attempt events.
* [QR code types](https://docs.trio.com.br/v2/guides/pix/qr-codes.md): the QR code the payer scans to authorize a recurrence.
* [Create a boleto](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md): the fine, interest and discount rules in detail.
* [Receivables overview](https://docs.trio.com.br/v2/guides/receivables/overview.md): all cash-in guides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.