Pular para o conteúdo

Automatic Pix

Lina initiation APIs for Automatic Pix streamline Open Finance automatic payments (recurring contracts with the account holder). They reduce integration effort so you can offer scheduled collections with a modern payer experience.

The high-level journey matches Smart Pix (token, institutions, recurring consent, bank redirect, callback, poll consent, create payment) but the product contract uses recurringConfiguration.automatic (fixed/variable amounts, intervals, referenceStartDate, first payment, etc.), not the Sweeping configuration used by Smart Pix.

Prerequisites

  1. Get your credentials — OAuth 2.0 access token.
  2. Onboarding — allow-listed redirectUri domains.

Stage 0 — Contract creation and first payment

  1. Get registered participants with subTenantId.
  2. Create recurring consent with organisationId, authorisationServerId, User-Agent, and recurringConsent including recurringConfiguration.automatic and recurringConsent.redirectUri.
  3. On 201 Created, persist data.id (automatic payment request id) and data.consentId, then redirect the payer to data.redirectUrl.
  4. After consent at the holder, the browser returns to your redirectUri. That URL is your responsibility (hosting, TLS, allow-list).
  5. Poll Get payment request with {automaticPaymentsRequestId} = data.id until consentStatus is AUTHORISED.
  6. Create recurring payment with recurringConsentId = data.consentId, respecting cycle and scheduling rules below.
Stage 0 — Automatic Pix: institution selection, recurring consent, holder redirect, callback, poll request, first recurring payment

Stage 1 — Further payments (same contract)

When consent is already AUTHORISED, call Create recurring payment without a new bank redirect. Use List payments by sub-tenant or List payments by tenant to monitor legs when needed.

Stage 1 — New Automatic Pix payment without new consent redirect

Payment reference and billing cycles

Open Finance automatic payments use a payment reference (in the regulatory API, /data/paymentReference) to identify the billing cycle a recurring payment belongs to. Your integration should set the corresponding fields as required by the Automatic consent (referenceStartDate, interval such as SEMANAL, and related configuration).

The cycle boundaries depend on the interval agreed in the consent:

Weekly (SEMANAL)

The week runs from 00:00 on the calendar day in /data/recurringConfiguration/automatic/referenceStartDate through the day immediately before that weekday in the next cycle.
Example: Authorisation on 29 June; reference start 23 July. First cycle: 23/07–29/07; second: 30/07–05/08; and so on.

Monthly (MENSAL)

From 00:00 on referenceStartDate through 23:59 on the day before that calendar day in the next month.
Example: Reference 23 July — each cycle runs from the 23rd through the 22nd of the following month (e.g. 23/07–22/08, 23/08–22/09).

Quarterly (TRIMESTRAL)

Same day-of-month rule as monthly, but the cycle spans three months.
Example: Start 23 July — first cycle 23/07–22/10.

Semi-annual (SEMESTRAL)

Same anchor; cycle spans six months.
Example: Start 23 July — first cycle 23/07–22/01.

Annual (ANUAL)

Same anchor; cycle spans twelve months.
Example: Start 23 July — first cycle 23/07–22/07 (next year).

Retries (intraday and subsequent days)

When settlement fails, Automatic Pix allows retry windows (intraday and, under rules, extraday attempts). Whether a new end-to-end id is required, how many attempts are allowed, and timing depend on the arrangement and the error code. Summarise from the official guide:

Tentativas intradia e extradia para Pix automático v2.2.0

Use Retry recurring payment with the originalRecurringPaymentId of the failed leg and a new settlement date (and endToEndId when your flow must supply a new identifier per the table in that document).

Retry flow — initiator calls POST retry with originalRecurringPaymentId after a failed settlement

API reference

See the Automatic Pix group in the sidebar.