Skip to navigation

Pix Automático — overview

Pix Automático is the recurring charge of the Pix scheme. The payer authorizes once in their bank app, and your account schedules each charge with no new confirmation. The CorpX account is always the receiver.

The automatic_pix feature starts disabled for every tenant. While it is off, every route under /v1/accounts/{accountId}/pix/automatic returns 403 feature_disabled. CorpX enables the feature in the admin panel after the contract. Disabling it later does not cancel an authorized recurrence.

Credential scope: pix.automatic. Reads also accept read. In the panel, viewing requires pix_automatic.view and issuing or postponing requires pix_automatic.manage.

How a recurrence starts

PathRouteWhen to use
Authorization requestPOST /pix/automatic/recurrencesYou already have the payer’s bank, branch and account. The request reaches their bank app.
Immediate composite QRPOST /pix/automatic/composite-qr-codes/staticThe payer pays the first charge now and, in the same QR, authorizes the next ones.
Due-date composite QRPOST /pix/automatic/composite-qr-codes/due-dateSame as above, with due date, interest, penalty, discount and deduction.

Details in Recurrences and composite QR.

Lifecycle

recurrence awaiting_authorization ──► authorized ──► (schedulings)
│ │
├──► rejected └──► canceled
├──► expired
└──► request_failed / authorization_failed
scheduling created ──► confirmed ──► settled
│ │
│ └──► settlement failed ──► retry (up to 3 dates)
└──► rejected / confirmation_failed / expired

Every relevant change emits a pix.automatic.* webhook and a pix_automatic.* event in the timeline, anchored on the recurrenceId.

WebhookWhen
pix.automatic.recurrence.authorizedThe payer authorized. From now on you schedule.
pix.automatic.recurrence.rejectedThe payer or their bank rejected.
pix.automatic.recurrence.expiredThe request expired without an answer, or the recurrence was canceled.
pix.automatic.recurrence.failedThe request failed before reaching the payer.
pix.automatic.scheduling.confirmedThe payer’s bank confirmed the scheduled charge.
pix.automatic.scheduling.rejectedThe payer’s bank rejected the charge.
pix.automatic.scheduling.failedThe charge was not confirmed in time.
pix.automatic.settlement.completedThe money arrived in the account. pix.in.completed is also sent.
pix.automatic.settlement.failedThe money did not arrive. A retry can be requested.
pix.automatic.qrcode.paidThe composite QR was paid. pix.in.completed is also sent.

Payloads in Webhooks.

Two identifiers

  • recurrenceId is the UUID the API returns on creation. It is the recurrence id in this API, in webhooks and in the timeline.
  • recurrenceIdentifier (RR… or RN…) is the Pix scheme id. It appears once the scheme assigns it and is what the payer sees in their bank.

Every route with {recurrenceId} accepts both. RR…/RN… is only recognized after the recurrence went through this API or a webhook of the account.

Next steps

  1. Recurrences and composite QR: create, list and get.
  2. Schedulings and retries: charge, postpone and retry.