Pix Automático

Pix Automático lets a receiver (CNPJ) charge a payer (CPF or CNPJ) on a recurring basis after a single authorization in the payer's banking app. LB Pay implements Journey 3: the payer authorizes the recurrence together with the first payment, by scanning one composite QR code.

info

Pix Automático is standardized and regulated by the Central Bank of Brazil (BCB). Amounts are fixed per recurrence: every cycle charges the same value.

How the flow works

1. Create the recurrence — POST /v1/pix/automatic/recurrences returns the resource with textContent, an EMV payload for the composite QR (first payment + recurrence authorization in one code).
2. Payer scans the QR — the payer's PSP resolves the embedded location Rec (GET /rec/{accessToken}, public) and presents the authorization journey.
3. First payment settles — the recurrence reports statusDetailed=FIRST_PAYMENT_SUCCESS.
4. Payer PSP confirms the authorization — the recurrence becomes AUTHORIZED / VALIDATION_SUCCEEDED. You receive the pixAutomaticRecurrenceAuthorized webhook.
5. Cycle charges are scheduled — each cycle produces a schedule that is sent to the payer PSP ahead of the due date and settles through the SPI on the due date. You receive pixAutomaticScheduleSettled on success.
6. Retries when allowed — if the recurrence has allowPostDuePayment=true, a failed charge can be retried up to 3 times within 7 calendar days after the due date.

Endpoints

Method	Path	Purpose
POST	/v1/pix/automatic/recurrences	Create a recurrence + composite QR
GET	/v1/pix/automatic/recurrences	List recurrences (cursor pagination; filter by status, payerTaxId)
GET	/v1/pix/automatic/recurrences/{id}	Read a recurrence
POST	/v1/pix/automatic/recurrences/{id}/cancel	Cancel a recurrence (cancels open schedules too)
POST	/v1/pix/automatic/recurrences/{id}/schedules	Create the cycle charge (due date 2–10 calendar days ahead)
GET	/v1/pix/automatic/schedules	List scheduled charges (filter by status, recurrenceId)
GET	/v1/pix/automatic/schedules/{id}	Read a scheduled charge
POST	/v1/pix/automatic/schedules/{id}/cancel	Cancel a scheduled charge (until 22:00 of D-1)
POST	/v1/pix/automatic/schedules/{id}/post-due-retries	Command a post-due retry (up to 3 dates within 7 days)
PUT	/v1/webhook	Account webhook (shared with every Pix event): URL, authentication and optional events filter — see Webhooks

Lists use cursor pagination: { "object": "list", "data": [...], "hasMore": true, "nextCursor": "..." } — pass nextCursor back as cursor.

Full request/response reference: API Reference — Pix Automático.

Conventions

• Auth: Authorization: Bearer <JWT> — same credentials as the other LB Pay APIs. Resources are scoped to your wallet; reading another wallet's resource returns 403.
• Idempotency: every POST carries its own externalId in the body (max 255 chars). Same externalId + same body replays the stored response (kept for 48 h); same externalId + different body returns 409 IDEMPOTENCY_ERROR.
• Money: integers in centavos. 1000 = R$ 10,00. Valid range: R$ 1,00 to R$ 1.000.000,00.
• Casing: request and response bodies are camelCase.
• Dates: YYYY-MM-DD (Brasília calendar); timestamps ISO 8601.

Business rules to plan around

Rule	Value
Receiver document	CNPJ, numeric or alphanumeric
Payer document	CPF or CNPJ (numeric or alphanumeric)
Amount	Fixed per recurrence, R$ 1,00 – R$ 1.000.000,00
Frequencies	WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL
Cycles (totalCharges)	1 – 999
Journey expiration (expiresIn)	60 s – 30 calendar days
firstPaymentDate	≥ 2 calendar days after the journey expiration
Repeat journeys	A pending or payer-rejected journey for the same payer blocks a new one for 30 days
Schedule cancellation cutoff	22:00 (America/Sao_Paulo) of the day before the due date
Post-due retries	Up to 3 dates, within 7 calendar days after the due date, same amount

Testing in sandbox

In production the payer side is driven by real banking apps — but in sandbox you can simulate every payer action and test the full journey end to end, including your webhook handling (events are delivered to your registered account webhook). The simulator endpoints live under /v1/pix/automatic/simulations and return 404 in production.

The complete happy path:

# 1. Create the recurrence (returns the composite QR)
POST /v1/pix/automatic/recurrences

# 2. Simulate the payer scanning and paying the QR (first Pix settles)
POST /v1/pix/automatic/simulations/recurrences/{id}/first-payment

# 3. Simulate the payer PSP approving the authorization
POST /v1/pix/automatic/simulations/recurrences/{id}/authorization
{ "outcome": "APPROVED" }
# → recurrence AUTHORIZED — webhook pixAutomaticRecurrenceAuthorized fires

# 4. Create the cycle charge (due date 2-10 calendar days ahead)
POST /v1/pix/automatic/recurrences/{id}/schedules

# 5. Simulate the payer PSP accepting the charge
POST /v1/pix/automatic/simulations/schedules/{scheduleId}/payer-response
{ "outcome": "ACCEPTED" }

# 6. Simulate settlement on the due date
POST /v1/pix/automatic/simulations/schedules/{scheduleId}/settlement
{ "outcome": "SETTLED" }
# → schedule SUCCESS — webhook pixAutomaticScheduleSettled fires

Every failure path is also simulable:

Scenario	How
Rejection with any scheme code	{ "outcome": "REJECTED", "rejectionCode": "AC05" } on steps 3, 5 or 6
Divergent payer or amount on the first payment	Body overrides on step 2 (payerTaxId, amount) → real EXPECTED_PAYER_MISMATCH / FIRST_PAYMENT_AMOUNT_MISMATCH
Payer never completes the journey	POST .../recurrences/{id}/expiration
Payer cancels the recurrence in their app	POST .../recurrences/{id}/payer-cancellation
Payer PSP cancels a charge (camt.055)	POST .../schedules/{id}/payer-cancellation with CCLD, or FAIL to also receive the auto-created same-day RIFL
Payer PSP never answers the instruction	POST .../schedules/{id}/payer-response-timeout
Refund of a settled charge (REFU/DICT)	POST .../schedules/{id}/refund then POST .../refunds/{id}/result
Refund of the first payment	POST .../recurrences/{id}/first-payment-refund

Full reference: API Reference — Pix Automático.

Current scope

This is the current product phase — the API is versioned and these limits may be lifted in future releases:

Dimension	Current scope
Journey	Journey 3 only (authorization + first payment in one composite QR). Journeys 1, 2 and 4 are not offered.
Amount	Fixed or variable. Fixed: amount charges every cycle. Variable: omit amount, optionally set minimumAmount (the floor for the payer's own maximum) and declare firstPaymentAmount; each cycle charge then has a free amount (R$ 1,00 – R$ 1.000.000,00). Charges above the payer's private maximum are rejected by the payer PSP with AM02 — you may charge the same cycle again.
Payer document	CPF or CNPJ, including alphanumeric CNPJs (IN RFB 2.229/2024).
Retry policy	Equivalent to BACEN PERMITE_3R_7D when allowPostDuePayment=true, NAO_PERMITE otherwise.

BACEN vocabulary mapping

If you also integrate PSPs that expose the raw Banco Central API Pix (/rec, /cobr), this is how our vocabulary maps:

LB Pay	BACEN API Pix
recurrence	Rec (recorrência)
schedule	CobR (cobrança recorrente)
POST /v1/pix/automatic/recurrences	POST /rec (+ locrec composite QR, Jornada 3)
GET /v1/pix/automatic/recurrences	GET /rec
POST .../recurrences/{id}/cancel	PATCH /rec/{idRec} with cancellation
POST .../recurrences/{id}/schedules	PUT /cobr/{txid} / POST /cobr
POST .../schedules/{id}/post-due-retries	POST /cobr/{txid}/retentativa/{data}
PUT /v1/webhook (account webhook, events pixAutomatic…)	`PUT
recUrlAccessToken / GET /rec/{accessToken}	recUrlAccessToken payload location
status: PENDING / AUTHORIZED / CANCELLED / EXPIRED / FAILED	Rec CRIADA / APROVADA / CANCELADA / EXPIRADA / REJEITADA
Schedule CREATED / PENDING / SCHEDULED / SUCCESS / CANCELLED / FAILED	CobR CRIADA / ATIVA / AGENDADA / CONCLUIDA / CANCELADA / REJEITADA-EXPIRADA
purpose: AGND / NTAG / RIFL	Same BACEN attempt types
amount (fixed) / minimumAmount (variable floor)	valor.valorRec / valor.valorMinimoRecebedor (mutually exclusive; both absent = open value)
allowPostDuePayment	politicaRetentativa (PERMITE_3R_7D / NAO_PERMITE)
frequency: WEEKLY / MONTHLY / QUARTERLY / SEMIANNUAL / ANNUAL	periodicidade: SEMANAL / MENSAL / TRIMESTRAL / SEMESTRAL / ANUAL

Scheme rejection codes received from the payer PSP (e.g. AC05, AM02, DENC) are passed through verbatim in the schedule's rejectionCode field — the full catalog with meanings and retry guidance is in Errors — scheme rejection codes. Codes generated by LB Pay itself (PAYER_RESPONSE_TIMEOUT, RIFL_CUTOFF_EXCEEDED, REGULATORY_SEND_FAILED) are documented in the status machine.

See also

• Status Machine — Pix Automático
• Errors — Pix Automático
• Webhooks — Pix Automático events