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

# Pix Automático — visão geral

O Pix Automático é a cobrança recorrente do arranjo Pix. O pagador autoriza uma vez no app do banco dele, e a sua conta agenda cada cobrança sem nova confirmação. A conta CorpX é sempre a **recebedora**.

A feature `automatic_pix` **nasce desligada para todos os tenants**. Enquanto estiver off, toda rota em `/v1/accounts/{accountId}/pix/automatic` responde **403** `feature_disabled`. A CorpX liga a feature pelo painel administrativo depois do contrato. Desligar depois não cancela recorrência já autorizada.

Escopo da credencial: `pix.automatic`. As leituras também aceitam `read`. No painel, ver exige `pix_automatic.view` e emitir ou adiar exige `pix_automatic.manage`.

## Como começa uma recorrência

| Caminho                    | Rota                                              | Quando usar                                                                         |
| -------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Pedido de autorização      | `POST /pix/automatic/recurrences`                 | Você já tem banco, agência e conta do pagador. O pedido chega ao app do banco dele. |
| QR composto imediato       | `POST /pix/automatic/composite-qr-codes/static`   | O pagador paga a primeira cobrança agora e, no mesmo QR, autoriza as próximas.      |
| QR composto com vencimento | `POST /pix/automatic/composite-qr-codes/due-date` | Igual ao anterior, com vencimento, juros, multa, desconto e abatimento.             |

Detalhes em [Recorrências e QR composto](/baas/guias/pix-automatico/recorrencias).

## Ciclo de vida

```text
recorrência     awaiting_authorization ──► authorized ──► (agendamentos)
                       │                     │
                       ├──► rejected          └──► canceled
                       ├──► expired
                       └──► request_failed / authorization_failed

agendamento     created ──► confirmed ──► settled
                   │            │
                   │            └──► liquidação falhou ──► retentativa (até 3 datas)
                   └──► rejected / confirmation_failed / expired
```

Cada mudança relevante gera um webhook `pix.automatic.*` e um evento `pix_automatic.*` na [timeline](/baas/guias/conta/timeline), ancorado no `recurrenceId`.

| Webhook                               | Quando                                                         |
| ------------------------------------- | -------------------------------------------------------------- |
| `pix.automatic.recurrence.authorized` | O pagador autorizou. A partir daqui você agenda.               |
| `pix.automatic.recurrence.rejected`   | O pagador ou o banco dele recusou.                             |
| `pix.automatic.recurrence.expired`    | O pedido expirou sem resposta, ou a recorrência foi cancelada. |
| `pix.automatic.recurrence.failed`     | O pedido falhou antes de chegar ao pagador.                    |
| `pix.automatic.scheduling.confirmed`  | O banco do pagador confirmou a cobrança agendada.              |
| `pix.automatic.scheduling.rejected`   | O banco do pagador recusou a cobrança.                         |
| `pix.automatic.scheduling.failed`     | A cobrança não foi confirmada a tempo.                         |
| `pix.automatic.settlement.completed`  | O dinheiro entrou na conta. Também sai `pix.in.completed`.     |
| `pix.automatic.settlement.failed`     | O dinheiro não entrou. Dá para pedir retentativa.              |
| `pix.automatic.qrcode.paid`           | O QR composto foi pago. Também sai `pix.in.completed`.         |

Payloads em [Webhooks](/baas/guias/conta/webhooks).

## Dois identificadores

* `recurrenceId` é o UUID que a API devolve na criação. É o id da recorrência nesta API, no webhook e na timeline.
* `recurrenceIdentifier` (`RR…` ou `RN…`) é o id do arranjo Pix. Aparece quando o arranjo atribui e é o que o pagador vê no banco dele.

Toda rota com `{recurrenceId}` aceita os dois. O `RR…`/`RN…` só é reconhecido depois que a recorrência passou por esta API ou por um webhook da conta.

## Próximos passos

1. [Recorrências e QR composto](/baas/guias/pix-automatico/recorrencias): criar, listar e consultar.
2. [Agendamentos e retentativas](/baas/guias/pix-automatico/agendamentos): cobrar, adiar e tentar de novo.