Skip to navigation

Schedulings and retries

With the recurrence authorized, each charge is a scheduling. The payer’s bank confirms it and debits on the date. Scheduling and requesting retries move money: they are financial operations and only accept an M2M credential with the pix.automatic scope. A panel user token gets 403.

Schedule a charge

POST /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/schedulings
{
"dueDate": "2026-11-25",
"value": 149.9,
"message": "November installment",
"adjustToBusinessDay": true
}
FieldRule
dueDateRequired. Within the current cycle and at least 2 days ahead. Otherwise 422 automatic_pix_date_out_of_window.
valueRequired for variable-amount recurrences. Cannot exceed maximumValue nor payerMaximumValue (422 automatic_pix_value_above_payer_limit). For a fixed amount, the charge is always the recurrence value.
adjustToBusinessDaytrue moves the date to the next business day.

Each cycle accepts one active scheduling; another one in the same cycle returns 409 automatic_pix_scheduling_conflict. A recurrence that is not authorized returns 409 automatic_pix_recurrence_not_authorized.

The response is 201 with the schedulingId. Then the webhooks follow:

  1. pix.automatic.scheduling.confirmed, when the payer’s bank confirms. If it rejects, .rejected; if it does not answer in time, .failed.
  2. On the date, pix.automatic.settlement.completed and pix.in.completed, with the same endToEndId. Do not add both up.
  3. If the money does not arrive, pix.automatic.settlement.failed with settlementId and settlementStatus (insufficient_balance, not_settled or not_settled_with_error).

Get and list

GET /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/schedulings
GET /v1/accounts/{accountId}/pix/automatic/schedulings/{schedulingId}

Live reads. The scheduling carries status, history, endToEndId and, when it exists, settlement with settlementId, status and settledAt. Retries appear in the same list with purpose: retry.

Postpone

PATCH /v1/accounts/{accountId}/pix/automatic/schedulings/{schedulingId}
{ "dueDate": "2026-11-28", "adjustToBusinessDay": true }

Only while the scheduling is created, before it goes to the payer’s bank; after that the response is 409 automatic_pix_scheduling_conflict. The payer’s bank confirms the new date. Postponing is not a financial operation: the panel can do it too.

Retry

Applies to recurrences created with paymentRetry: true, after pix.automatic.settlement.failed.

GET /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/settlements/{settlementId}/retry-dates
POST /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/settlements/{settlementId}/retries

The GET returns suggestedDates, remainingAttempts, maxRetryDates and windowEnd. A retry must fall after the original due date, within 7 calendar days and in the same cycle.

{ "dates": ["2026-11-27", "2026-12-02"] }

From 1 to 3 dates, among the suggested ones. Each becomes a scheduling with purpose: retry and follows the same webhook flow. A retry that is not allowed (no paymentRetry, already settled, an attempt in progress that day, or dates exhausted) returns 409 automatic_pix_retry_not_allowed.