> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Recurrences and composite QR

Prerequisites in [Pix Automático — overview](/baas/guias/pix-automatico/visao-geral): the `automatic_pix` feature enabled and the `pix.automatic` scope.

## Recurrence terms

The three creation paths share the same terms:

| Field                  | Required                  | Rule                                                                                              |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
| `frequency`            | yes                       | `weekly`, `monthly`, `quarterly`, `semiannual` or `annual`.                                       |
| `firstPaymentDate`     | yes                       | `YYYY-MM-DD`.                                                                                     |
| `lastPaymentDate`      | no                        | Without it the recurrence has no end. Cannot be before `firstPaymentDate`.                        |
| `value`                | one of the two            | Fixed amount of every charge.                                                                     |
| `maximumValue`         | one of the two            | Ceiling for variable-amount charges. Sending both returns **422** `automatic_pix_value_mismatch`. |
| `paymentRetry`         | no                        | `true` allows retries after a failed settlement.                                                  |
| `contract.number`      | yes                       | Contract number the payer sees.                                                                   |
| `contract.description` | no                        | Text shown to the payer.                                                                          |
| `debtor`               | no (yes on composite QRs) | `taxNumber` and `name` of whom the charge refers to, when it is not the payer.                    |

The scheme blocks the same contract for 24 hours, a pending request for the same contract and payer, and an identical proposal rejected or canceled less than 30 days ago. In those cases the response is **409** `automatic_pix_contract_blocked`.

## Authorization request

```
POST /v1/accounts/{accountId}/pix/automatic/recurrences
```

```json
{
  "frequency": "monthly",
  "firstPaymentDate": "2026-11-25",
  "lastPaymentDate": "2027-10-25",
  "value": 149.9,
  "paymentRetry": true,
  "contract": { "number": "CONTRATO-1001", "description": "Monthly plan" },
  "payer": {
    "ispb": "99999004",
    "taxNumber": "12345678909",
    "branch": "0001",
    "account": "123456",
    "ibgeCode": "3550308",
    "name": "MARIA DA SILVA"
  },
  "requestExpiration": "2026-11-10T23:59:59-03:00"
}
```

`payer.ispb`, `payer.taxNumber`, `payer.branch`, `payer.account` and `payer.ibgeCode` (7-digit IBGE code of the payer's city) are required; a missing one returns **400** `missing_field`, and a malformed `ibgeCode` returns **400** `invalid_field`. `requestExpiration` is optional: after today and up to 30 days ahead, in Brasília time; without it, the settlement bank uses 30 days. An ISPB that does not exist or is not in Pix Automático returns **422** `automatic_pix_payer_bank_unavailable`. The receiving account must be an active legal entity; otherwise **422** `automatic_pix_receiver_ineligible`.

The response is **201** with the recurrence in `awaiting_authorization`. Keep the `recurrenceId`. The payer's decision arrives by webhook: `pix.automatic.recurrence.authorized`, `.rejected`, `.expired` or `.failed`.

## Composite QR

One QR that charges now and, once paid, takes the payer to authorize the recurrence.

```
POST /v1/accounts/{accountId}/pix/automatic/composite-qr-codes/static
POST /v1/accounts/{accountId}/pix/automatic/composite-qr-codes/due-date
```

```json
{
  "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pixKey": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
  "value": 49.9,
  "message": "First installment",
  "requestExpiration": "2026-11-20T23:59:59-03:00",
  "recurrence": {
    "frequency": "monthly",
    "firstPaymentDate": "2026-12-25",
    "maximumValue": 200,
    "contract": { "number": "CONTRATO-1001" },
    "debtor": { "taxNumber": "12345678909", "name": "MARIA DA SILVA" }
  }
}
```

* `identifier` is your UUID, unique per account. A value that is not a UUID returns **400** `invalid_field`; repeating it returns **409** `automatic_pix_identifier_in_use`.
* `requestExpiration` is required: deadline of the recurrence offer, after today and up to 30 days ahead. Without an offset, Brasília time applies.
* `recurrence.debtor` (`taxNumber` and `name`) is required on composite QRs.
* `pixKey` is a key of the account itself.
* `value` is the amount of this first charge. The terms of the next ones go in `recurrence`.
* On the `due-date` route, `dueDate` is required. `daysAfterDueDate`, `deduction`, `discount`, `interest` and `penalty` are optional. The `static` route ignores those fields.

The **201** response carries `pixCopyPaste`, `image` (base64 PNG), `qrCodeId` and the `recurrenceId`. When the payer pays, `pix.in.completed` (the credit) and `pix.automatic.qrcode.paid` (the link to the recurrence) are sent. Then the authorization result arrives as `pix.automatic.recurrence.*`.

## List and get

```
GET /v1/accounts/{accountId}/pix/automatic/recurrences
GET /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}
```

Both reads are live at the settlement bank. The list filters by `startDate`, `endDate` (exclusive), `status`, `journey`, `frequency`, `payerTaxNumber` and `debtorTaxNumber`. Without a period, the last 30 days in the Brasília time zone apply. Pagination uses `page` (from 1) and `pageSize` (up to 100), and the response carries `items`, `totalItems`, `totalPages` and `hasNext`.

The single read carries `history` with every status change and, after authorization, `payerMaximumValue`: the ceiling the payer chose. A recurrence of another account returns **404**.