Skip to navigation

Agendamentos e retentativas

Com a recorrência authorized, cada cobrança é um agendamento. O banco do pagador confirma e debita na data. Agendar e pedir retentativa movem dinheiro: são operações financeiras e só aceitam credencial M2M com o escopo pix.automatic. Token de usuário do painel recebe 403.

Agendar uma cobrança

POST /v1/accounts/{accountId}/pix/automatic/recurrences/{recurrenceId}/schedulings
{
"dueDate": "2026-11-25",
"value": 149.9,
"message": "Mensalidade de novembro",
"adjustToBusinessDay": true
}
CampoRegra
dueDateObrigatório. Dentro do ciclo vigente e pelo menos 2 dias à frente. Fora disso, 422 automatic_pix_date_out_of_window.
valueObrigatório em recorrência de valor variável. Não pode passar de maximumValue nem do payerMaximumValue (422 automatic_pix_value_above_payer_limit). Em valor fixo, a cobrança é sempre o value da recorrência.
adjustToBusinessDaytrue leva a data para o próximo dia útil.

Cada ciclo aceita um agendamento ativo; outro no mesmo ciclo responde 409 automatic_pix_scheduling_conflict. Recorrência que não está authorized responde 409 automatic_pix_recurrence_not_authorized.

A resposta é 201 com o schedulingId. Depois vêm os webhooks:

  1. pix.automatic.scheduling.confirmed, quando o banco do pagador confirma. Se recusar, sai .rejected; se não responder a tempo, .failed.
  2. Na data, pix.automatic.settlement.completed e pix.in.completed, com o mesmo endToEndId. Não some os dois.
  3. Se o dinheiro não entrar, sai pix.automatic.settlement.failed com settlementId e settlementStatus (insufficient_balance, not_settled ou not_settled_with_error).

Consultar e listar

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

Leituras ao vivo. O agendamento traz status, history, endToEndId e, quando existe, settlement com settlementId, status e settledAt. Retentativas aparecem na mesma lista com purpose: retry.

Adiar

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

Só enquanto o agendamento está created, antes de seguir para o banco do pagador; depois disso a resposta é 409 automatic_pix_scheduling_conflict. O banco do pagador confirma a nova data. Adiar não é operação financeira: o painel também pode.

Retentativa

Vale para recorrência criada com paymentRetry: true, depois de 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

O GET devolve suggestedDates, remainingAttempts, maxRetryDates e windowEnd. A retentativa precisa cair depois do vencimento original, em até 7 dias corridos e no mesmo ciclo.

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

De 1 a 3 datas, das sugeridas. Cada uma vira um agendamento com purpose: retry e segue o mesmo fluxo de webhooks. Retentativa não permitida (sem paymentRetry, liquidação já feita, tentativa em andamento no dia ou datas esgotadas) responde 409 automatic_pix_retry_not_allowed.