> This page is for BaaS.

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

# Recorrências e QR composto

Pré-requisitos em [Pix Automático — visão geral](/baas/guias/pix-automatico/visao-geral): feature `automatic_pix` ligada e escopo `pix.automatic`.

## Termos da recorrência

Os três caminhos de criação usam os mesmos termos:

| Campo                  | Obrigatório              | Regra                                                                                                  |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `frequency`            | sim                      | `weekly`, `monthly`, `quarterly`, `semiannual` ou `annual`.                                            |
| `firstPaymentDate`     | sim                      | `YYYY-MM-DD`.                                                                                          |
| `lastPaymentDate`      | não                      | Sem ele, a recorrência não tem fim. Não pode ser antes de `firstPaymentDate`.                          |
| `value`                | um dos dois              | Valor fixo de toda cobrança.                                                                           |
| `maximumValue`         | um dos dois              | Teto para cobranças de valor variável. Enviar os dois responde **422** `automatic_pix_value_mismatch`. |
| `paymentRetry`         | não                      | `true` permite retentativa depois de uma liquidação que falhou.                                        |
| `contract.number`      | sim                      | Número do contrato que o pagador vê.                                                                   |
| `contract.description` | não                      | Texto exibido ao pagador.                                                                              |
| `debtor`               | não (sim no QR composto) | `taxNumber` e `name` de quem a cobrança se refere, quando não é o pagador.                             |

O arranjo bloqueia o mesmo contrato por 24 horas, um pedido pendente para o mesmo contrato e pagador e uma proposta idêntica recusada ou cancelada há menos de 30 dias. Nesses casos a resposta é **409** `automatic_pix_contract_blocked`.

## Pedido de autorização

```
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": "Plano mensal" },
  "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` e `payer.ibgeCode` (código IBGE do município do pagador, 7 dígitos) são obrigatórios; faltando um, a resposta é **400** `missing_field`, e `ibgeCode` fora do formato responde **400** `invalid_field`. `requestExpiration` é opcional: depois de hoje e até 30 dias, no fuso de Brasília; sem ele, o liquidante usa 30 dias. ISPB inexistente ou fora do Pix Automático responde **422** `automatic_pix_payer_bank_unavailable`. A conta recebedora precisa ser PJ ativa; caso contrário, **422** `automatic_pix_receiver_ineligible`.

A resposta é **201** com a recorrência em `awaiting_authorization`. Guarde o `recurrenceId`. A decisão do pagador chega por webhook: `pix.automatic.recurrence.authorized`, `.rejected`, `.expired` ou `.failed`.

## QR composto

Um QR que cobra agora e, ao ser pago, leva o pagador a autorizar a recorrência.

```
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": "Primeira mensalidade",
  "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` é um UUID seu, único por conta. Fora do formato UUID, a resposta é **400** `invalid_field`; repetir responde **409** `automatic_pix_identifier_in_use`.
* `requestExpiration` é obrigatório: validade da oferta de recorrência, depois de hoje e até 30 dias. Sem offset, vale o fuso de Brasília.
* `recurrence.debtor` (`taxNumber` e `name`) é obrigatório no QR composto.
* `pixKey` é uma chave da própria conta.
* `value` é o valor desta primeira cobrança. Os termos das próximas ficam em `recurrence`.
* Na rota `due-date`, `dueDate` é obrigatório. `daysAfterDueDate`, `deduction`, `discount`, `interest` e `penalty` são opcionais. Na rota `static` esses campos são ignorados.

A resposta **201** traz `pixCopyPaste`, `image` (PNG em base64), `qrCodeId` e o `recurrenceId`. Quando o pagador paga, saem `pix.in.completed` (o crédito) e `pix.automatic.qrcode.paid` (o vínculo com a recorrência). Depois vem o resultado da autorização em `pix.automatic.recurrence.*`.

## Listar e consultar

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

As duas leituras são ao vivo no liquidante. A lista filtra por `startDate`, `endDate` (exclusivo), `status`, `journey`, `frequency`, `payerTaxNumber` e `debtorTaxNumber`. Sem período, vale os últimos 30 dias no fuso de Brasília. A paginação usa `page` (a partir de 1) e `pageSize` (até 100), e a resposta traz `items`, `totalItems`, `totalPages` e `hasNext`.

A consulta individual traz `history` com cada mudança de status e, depois da autorização, `payerMaximumValue`: o teto que o pagador escolheu. Recorrência de outra conta responde **404**.