Automatic Pix

Automatic Pix (Pix Automático) is the Banco Central arrangement that lets you debit a payer's account on a recurring basis, without the payer approving each payment. The payer authorizes once, in their banking app; from then on, PixToPay issues the debits on the agreed schedule.

In this section you will find everything you need to charge subscriptions, monthly fees and recurring plans from your backend.

Recurrences
Authorization solicitations
Charges
Notifications
Complete walkthrough
Errors

Available Endpoints

• Production: https://api.pixtopay.com.br/v2/automatic-pix

Authentication is the same as the rest of the API: the Authorization: YOUR_API_KEY header on every request.

The two objects: recurrence and charge

The integration has two objects. The difference between them is the most important thing in this documentation:

Lifecycle

Three practical consequences:

• No API call moves a recurrence from CREATED to APPROVED. Approval is something the payer does inside their banking app. Your backend follows it; it cannot force it.
• PixToPay only creates charges under APPROVED recurrences. Until the payer authorizes, nothing is charged.
• You do not create charges: PixToPay does. Each cycle's charge is issued automatically charge_lead_days days before the due date: 5 by default, or the value from 3 to 10 you choose when creating the recurrence (Banco Central requires the debit instruction to be sent between 10 and 2 days before the due date). You are notified by the charge.created event, and you can cancel a specific cycle before its due date.

How each cycle's due date is calculated

The due date is calculated from schedule.start_date and the periodicity:

• Same day in the following periods. A monthly recurrence starting on October 15, 2026 falls due on the 15th of the following months.
• Shorter months use their last day. A recurrence starting on the 31st falls due on the last day of February, April and so on.
• Business days, if you want. By default the debit happens on the exact date, weekends and holidays included. With business_day_adjust: true when creating the recurrence, a due date that falls on a weekend or holiday moves to the next business day. The charge's due_date always carries the effective date.
• Journey 3. The activation payment is separate and covers no cycle: automatic charges start at schedule.start_date, as on any recurrence. To charge the activation today and the next debit a month from now, send start_date one month ahead.

The two authorization journeys

You choose one of the two for each recurrence. They cannot be combined.

The QR route is the default choice for most integrations: it does not require collecting bank details and works on any channel that can carry an image or copyable text. The notification route skips showing the QR, but requires you to have, and keep correct, the payer's branch, account and ISPB. Wrong details mean an alert that never arrives, with no visible error.

Variant: authorize and charge in the same scan (journey 3)

The QR route has a variant in which the first payment happens in the same scan that authorizes the recurrence. A single QR code charges, for example, the first monthly fee and authorizes the next ones.

To use it, send activation_amount in POST /recurrences. The API creates the immediate payment, binds it to the recurrence and returns everything in a single response.

• Always show the recurrence's code: qrcode (image to scan) and pix_copy_paste (copy-and-paste text). In journey 3, that code carries both things: the payment and the authorization.
• The activation payment appears in GET /charges as one of the recurrence's charges, with "type": "activation". It is paid on the spot, so it cannot be cancelled or rescheduled, and it produces no charge events. The payment arrives as a paid Pix deposit, like any other.

Statuses

Recurrence statuses

Charge statuses

A charge is born CREATED or already ACTIVE, depending on how fast the payer's bank answers. Treat both as "created successfully".

Debit attempt statuses

A charge may accumulate debit attempts. The attempts field in responses is their count; the status of the last attempt (last_attempt_status) comes in the notifications.

Authorization solicitation statuses

Only for the notification route.

The solicitation status describes the path of the alert, not the payer's decision. The decision appears in the recurrence status, which moves to APPROVED or REJECTED.

Periodicity

Retry policy

3R_7D is the arrangement's own naming: 3 retries, 7 days. Prefer ALLOWS_3R_7D unless you have a reason not to retry: it is the difference between losing a cycle to funds that arrived the next day and not losing it. The policy is set when the recurrence is created and cannot be changed afterwards.

Journey

Read-only field. You do not send it: the payer's institution classifies the journey when the authorization happens.

Endpoints

Creating charges is not on this list: PixToPay creates them, automatically.