Scheduled & recurring scheduled Pix

Scheduled Pix lets you initiate a single Pix payment that settles on a future date (D+N) instead of the same day. The payer authorises the consent once; the amount is debited on the scheduled settlement date according to the rules agreed with the account holder.

Recurring scheduled Pix covers a series of future settlements from one consent — daily, weekly, monthly, or on custom dates. Only one schedule shape may be sent per payment (single, daily, weekly, monthly, or custom). The OpenAPI contract enforces: the first settlement must be at least D+1 calendar day from consent creation; you may schedule up to 60 installments; and the last installment must fall within two years of consent creation (not from the first payment date).

These journeys reuse the same Open Finance initiation pattern as Instant Pix: list participants, create a consent, redirect the payer to the bank, then return to your redirectUri.

How the flow works

1. Call GET /api/v1/open-integration/participants/registered to retrieve institutions enabled for your ITP and let the payer pick their bank.
2. Call POST /api/v1/open-integration/consents with a payment payload that includes a schedule describing the future date(s) or recurrence. The response includes redirectUrl for bank authentication and consent approval.
3. After the payer finishes at the bank, they are redirected to your redirectUri with paymentLinkId in the query string — same behaviour as Instant Pix. Keep that URL registered and available (see Onboarding and Add a redirect domain).
4. Use GET /api/v1/payments/requests/{paymentRequestId} with the returned request id to confirm consent state (CONSUMIDO) and each row in payments[] (PENDENTE until the settlement day, then PAGO or an error state).

Flow diagram

On settlement day: webhook or active polling

When the calendar reaches each payment’s due date, Lina settles the Pix with the account holder. Your backend is not redirected again for that settlement. You learn the outcome in one of two ways:

• Webhook — If your sub-tenant has a payment webhook configured, Lina can push status updates (for example when a scheduled installment moves to PAGO or fails). Rely on idempotent handling and signature verification as documented for your integration.
• Active polling — If you do not use webhooks, or as a back-up, call Get payment request, Get payment by ID, Get payment by external ID, or Get payment by TxID on or after the due date until each payment reaches a terminal status.

Cancellations

You can stop future work in two ways:

• Cancel all future payments under a consent — use Cancel consent payments to cancel every pending installment tied to that consent in one call.
• Cancel a single future installment — use Cancel payment with the specific payment id when you only need to remove one scheduled charge while leaving the rest of the recurrence in place.

Both endpoints require the CPF of the person responsible for the cancellation in the request body, as defined in the API reference.

Payment status values

The same status enums apply as for Instant Pix. Request-level status reflects the consent; each row in payments[] has its own status through the lifecycle (PENDENTE until settlement, then PAGO, REJEITADO, CANCELADO, etc.).

Payment request status

Payment status

Next steps

• Get registered participants
• Create a consent
• Get payment request
• Get payment by ID
• Get payment by external ID
• Get payment by TxID
• Cancel consent payments
• Cancel payment