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

# Agendamentos e retentativas

Com a recorrência `authorized`, cada cobrança é um agendamento. O banco do pagador confirma e debita na data. Agendar e pedir retentativa movem dinheiro: são **operações financeiras** e só aceitam credencial M2M com o escopo `pix.automatic`. Token de usuário do painel recebe **403**.

## Agendar uma cobrança

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

```json
{
  "dueDate": "2026-11-25",
  "value": 149.9,
  "message": "Mensalidade de novembro",
  "adjustToBusinessDay": true
}
```

| Campo                 | Regra                                                                                                                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dueDate`             | Obrigatório. Dentro do ciclo vigente e pelo menos 2 dias à frente. Fora disso, **422** `automatic_pix_date_out_of_window`.                                                                                                 |
| `value`               | Obrigatório em recorrência de valor variável. Não pode passar de `maximumValue` nem do `payerMaximumValue` (**422** `automatic_pix_value_above_payer_limit`). Em valor fixo, a cobrança é sempre o `value` da recorrência. |
| `adjustToBusinessDay` | `true` leva a data para o próximo dia útil.                                                                                                                                                                                |

Cada ciclo aceita um agendamento ativo; outro no mesmo ciclo responde **409** `automatic_pix_scheduling_conflict`. Recorrência que não está `authorized` responde **409** `automatic_pix_recurrence_not_authorized`.

A resposta é **201** com o `schedulingId`. Depois vêm os webhooks:

1. `pix.automatic.scheduling.confirmed`, quando o banco do pagador confirma. Se recusar, sai `.rejected`; se não responder a tempo, `.failed`.
2. Na data, `pix.automatic.settlement.completed` e `pix.in.completed`, com o mesmo `endToEndId`. Não some os dois.
3. Se o dinheiro não entrar, sai `pix.automatic.settlement.failed` com `settlementId` e `settlementStatus` (`insufficient_balance`, `not_settled` ou `not_settled_with_error`).

## Consultar e listar

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

Leituras ao vivo. O agendamento traz `status`, `history`, `endToEndId` e, quando existe, `settlement` com `settlementId`, `status` e `settledAt`. Retentativas aparecem na mesma lista com `purpose: retry`.

## Adiar

```
PATCH /v1/accounts/{accountId}/pix/automatic/schedulings/{schedulingId}
```

```json
{ "dueDate": "2026-11-28", "adjustToBusinessDay": true }
```

Só enquanto o agendamento está `created`, antes de seguir para o banco do pagador; depois disso a resposta é **409** `automatic_pix_scheduling_conflict`. O banco do pagador confirma a nova data. Adiar não é operação financeira: o painel também pode.

## Retentativa

Vale para recorrência criada com `paymentRetry: true`, depois de `pix.automatic.settlement.failed`.

```
GET  /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/settlements/{settlementId}/retry-dates
POST /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/settlements/{settlementId}/retries
```

O `GET` devolve `suggestedDates`, `remainingAttempts`, `maxRetryDates` e `windowEnd`. A retentativa precisa cair depois do vencimento original, em até 7 dias corridos e no mesmo ciclo.

```json
{ "dates": ["2026-11-27", "2026-12-02"] }
```

De 1 a 3 datas, das sugeridas. Cada uma vira um agendamento com `purpose: retry` e segue o mesmo fluxo de webhooks. Retentativa não permitida (sem `paymentRetry`, liquidação já feita, tentativa em andamento no dia ou datas esgotadas) responde **409** `automatic_pix_retry_not_allowed`.