Agendador de PIX Automático (Beta)

Visão Geral #

O Agendador de PIX Automático é uma extensão do recurso PIX Automático da Pluggy que permite automatizar o agendamento de pagamentos recorrentes sem intervenção manual.

Em vez de chamar o endpoint de agendamento você mesmo para cada ciclo de pagamento, você pode habilitar o agendador ao criar a solicitação de pagamento. Uma vez que o pagador autoriza o consentimento, os pagamentos serão agendados automaticamente em cada ciclo de recorrência, sempre respeitando a janela de agendamento permitida (D+2 a D+10).

Como funciona #

Quando você cria uma solicitação de pagamento de PIX Automático com schedulerConfiguration.enabled: true, o sistema cuida do agendamento dos pagamentos para você. Após o pagador autorizar o consentimento, os pagamentos são agendados periodicamente de acordo com o interval e startDate configurados, dentro da janela permitida de D+2 a D+10. Isso continua automaticamente até que o consentimento expire ou seja cancelado.

Configuração #

Você configura o agendador no momento de criar a solicitação de pagamento de PIX Automático, através do objeto schedulerConfiguration:

{
  "schedulerConfiguration": {
    "enabled": true,
    "description": "Pagamento de assinatura mensal"
  }
}

Parâmetros #

Parâmetro	Tipo	Obrigatório	Descrição
`enabled`	`boolean`	Sim	Habilita o agendamento automático de pagamentos.
`description`	`string`	Não	Descrição para os pagamentos agendados (máx 140 caracteres). Se definido, substitui a `description` da solicitação de pagamento.
`valueForVariableAmount`	`number`	Condicional	Obrigatório quando o consentimento utiliza valores variáveis (`minimumVariableAmount` / `maximumVariableAmount`). Este é o valor padrão que será usado para cada pagamento agendado automaticamente. Deve estar dentro da faixa permitida. Não permitido quando o consentimento utiliza um `fixedAmount`.

Criando uma solicitação de pagamento com agendamento automático #

Exemplo de valor fixo #

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": "Assinatura mensal",
    "fixedAmount": 99.90,
    "interval": "MONTHLY",
    "startDate": "2025-07-01",
    "recipientId": "{recipient-id}",
    "schedulerConfiguration": {
      "enabled": true,
      "description": "Assinatura - Julho 2025"
    }
  }'

Exemplo de valor variável #

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": "Conta de utilidade",
    "minimumVariableAmount": 50.00,
    "maximumVariableAmount": 500.00,
    "interval": "MONTHLY",
    "startDate": "2025-07-01",
    "recipientId": "{recipient-id}",
    "schedulerConfiguration": {
      "enabled": true,
      "valueForVariableAmount": 150.00
    }
  }'

Lógica de agendamento #

Cálculo da data de pagamento #

Cada pagamento é agendado no início de seu ciclo de recorrência. Por exemplo, um consentimento MONTHLY começando em 1º de julho terá pagamentos agendados para 1º de julho, 1º de agosto, 1º de setembro, etc.

De acordo com as regulamentações do Banco Central, os pagamentos devem ser agendados entre D+2 e D+10. Se a próxima data de pagamento já tiver passado D+2, o agendador ajusta para a data mais próxima permitida.

O agendador para automaticamente quando o consentimento expira (expiresAt) ou é cancelado. Em ambos os casos, um webhook payment_request/updated é enviado com o status da solicitação de pagamento definido como EXPIRED ou CANCELED, respectivamente.

Regras de validação #

Cenário	Erro
Consentimento de valor variável sem `valueForVariableAmount` na configuração do agendador	`AUTOMATIC_PIX_SCHEDULER_MISSING_VALUE_FOR_VARIABLE_AMOUNT`
`valueForVariableAmount` está fora da faixa de `minimumVariableAmount` / `maximumVariableAmount`	`AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_IN_RANGE`
`valueForVariableAmount` é fornecido, mas o consentimento utiliza um `fixedAmount`	`AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_ALLOWED`

Intervalos suportados #

O agendador suporta todos os intervalos do PIX Automático:

WEEKLY — ciclos de 7 dias
MONTHLY — ciclos de mês calendário
QUARTERLY — ciclos de 3 meses
SEMESTER — ciclos de 6 meses
ANNUAL — ciclos de 12 meses