Pular para o conteúdo

Scheduled Pix (redirect)

Schedule one or recurring Pix payments. This is the exact same with-redirection journey as Instant Pix — the only difference is a payment.schedule on the consent. Present a schedule and the payment becomes scheduled; omit it and it settles immediately.

Method sequence

  1. participants.listMostUsed(subTenantId) (optional) — pick a bank (organisationId + authorisationServerId).
  2. consents.create({ organisationId, authorisationServerId, redirectUri, payment }) — same as Instant Pix, but the payment also carries a schedule. Returns CreatedPayment { id, redirectUrl }.
  3. [redirect] send the payer to created.redirectUrl to authorize in their bank, then they return to your redirectUri.
  4. payments.getRequest(created.id) — poll the status. Scheduled settlements stay PROGRAMADO until their date.

Schedule modes

Provide exactly one of the modes below on payment.schedule:

ModeFieldsMeaning
singledateOne payment on a date.
dailystartDate, quantityDaily, quantity times.
weeklydayOfWeek, startDate, quantityWeekly on a weekday.
monthlydayOfMonth, startDate, quantityMonthly on a day of month.
customdates[], additionalInformationExplicit list of dates.

startDate must be ≥ D+1, at most 60 installments, and the horizon must be ≤ 2 years from when the consent is created. dayOfWeek uses the API enum (SEGUNDA_FEIRA … DOMINGO).

Sequence diagram

Scheduled Pix — same as Instant Pix, but the consent carries a schedule; settlements stay PROGRAMADO until their date

Code

Identical to Instant Pix, with a schedule added to payment. The example below schedules a monthly payment for 12 installments.

const created = await client.consents.create({
organisationId,
authorisationServerId,
redirectUri: 'https://minha-loja.com.br/retorno',
payment: {
  value: 150.5,
  cpfCnpj: '12345678901',
  redirectUri: 'https://minha-loja.com.br/retorno',
  creditor,
  schedule: { monthly: { dayOfMonth: 10, startDate: '2026-08-01', quantity: 12 } },
  // Other modes:
  // single:  { single: { date: '2026-08-10' } }
  // weekly:  { weekly: { dayOfWeek: 'SEGUNDA_FEIRA', startDate: '2026-08-03', quantity: 8 } }
  // custom:  { custom: { dates: ['2026-08-10', '2026-09-10'], additionalInformation: '2x' } }
},
});
// Redirect to created.redirectUrl, then poll payments.getRequest(created.id)

Next steps