Automatic PIX Scheduler (Beta)

Overview

The Automatic PIX Scheduler is an extension of Pluggy's Automatic PIX feature that lets you automate the scheduling of recurring payments without manual intervention.

Instead of calling the schedule endpoint yourself for each payment cycle, you can enable the scheduler when creating the payment request. Once the payer authorizes the consent, payments will be automatically scheduled at each recurrence cycle, always respecting the allowed scheduling window (D+2 to D+10).

How it works

When you create an Automatic PIX payment request with schedulerConfiguration.enabled: true, the system takes care of scheduling payments for you. After the payer authorizes the consent, payments are periodically scheduled according to the configured interval and startDate, within the allowed D+2 to D+10 window. This continues automatically until the consent expires or is cancelled.

Configuration

You configure the scheduler at the time of creating the Automatic PIX payment request, via the schedulerConfiguration object:

{
  "schedulerConfiguration": {
    "enabled": true,
    "description": "Monthly subscription payment"
  }
}

Parameters

Parameter	Type	Required	Description
`enabled`	`boolean`	Yes	Enables automatic scheduling of payments.
`description`	`string`	No	Description for the scheduled payments (max 140 characters). If set, overrides the payment request's `description`.
`valueForVariableAmount`	`number`	Conditional	Required when the consent uses variable amounts (`minimumVariableAmount` / `maximumVariableAmount`). This is the default amount that will be used for each automatically scheduled payment. Must be within the allowed range. Not allowed when the consent uses a `fixedAmount`.

Creating a payment request with automatic scheduling

Fixed amount example

curl -X POST https://api.pluggy.ai/payments-requests/automatic-pix \
  -H "X-API-KEY: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Monthly subscription",
    "fixedAmount": 99.90,
    "interval": "MONTHLY",
    "startDate": "2025-07-01",
    "recipientId": "{recipient-id}",
    "schedulerConfiguration": {
      "enabled": true,
      "description": "Subscription - July 2025"
    }
  }'

Variable amount example

curl -X POST https://api.pluggy.ai/payments-requests/automatic-pix \
  -H "X-API-KEY: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Utility bill",
    "minimumVariableAmount": 50.00,
    "maximumVariableAmount": 500.00,
    "interval": "MONTHLY",
    "startDate": "2025-07-01",
    "recipientId": "{recipient-id}",
    "schedulerConfiguration": {
      "enabled": true,
      "valueForVariableAmount": 150.00
    }
  }'

Scheduling logic

Payment date calculation

Each payment is scheduled at the start of its recurrence cycle. For example, a MONTHLY consent starting on July 1st will have payments scheduled for July 1st, August 1st, September 1st, etc.

Per Central Bank regulations, payments must be scheduled between D+2 and D+10. If the next payment date has already passed D+2, the scheduler adjusts it to the earliest allowed date.

The scheduler automatically stops when the consent expires (expiresAt) or is cancelled.

Validation rules

Scenario	Error
Variable amount consent without `valueForVariableAmount` in scheduler config	`AUTOMATIC_PIX_SCHEDULER_MISSING_VALUE_FOR_VARIABLE_AMOUNT`
`valueForVariableAmount` is outside the `minimumVariableAmount` / `maximumVariableAmount` range	`AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_IN_RANGE`
`valueForVariableAmount` is provided but the consent uses a `fixedAmount`	`AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_ALLOWED`

Supported intervals

The scheduler supports all PIX Automático intervals:

WEEKLY — 7-day cycles
MONTHLY — Calendar month cycles
QUARTERLY — 3-month cycles
SEMESTER — 6-month cycles
ANNUAL — 12-month cycles