🚧

Pré-requisito

Esta página cobre o agendamento de cobranças subsequentes em uma recorrência já autorizada. Se você ainda não criou a autorização do PIX Automático (Jornada 3 ou 4) e não tem um receiver_recurrence_id em mãos, comece por Cobrar com PIX Automático via API.

❗️

Atenção

O disparo das cobranças não é realizado por esta API — o recebedor deve realizar uma chamada ao endpoint de criação de fatura para cada ciclo da recorrência, respeitando a janela de envio (entre 2 e 10 dias antes da liquidação).

Agendar Nova Cobrança com PIX Automático

Utilize o endpoint Criar Fatura — v1/invoices. Atente-se aos parâmetros:

• email — E-mail do cliente. Não obrigatório se utilizado customer_id.
• payable_with — Insira apenas o valor pix para disponibilizar apenas este método de pagamento para esta fatura. Para mais métodos, adicione os valores (separando-os por vírgula):

1. credit_card — Cartão de Crédito
2. bank_slip — Boleto Bancário. Torna os parâmetros name e cpf_cnpj do array payer obrigatórios
3. all — Todos

• automatic_pix - Dados do Payer (name e cpf_cnpj) se tornam obrigatórios ao utilizar esse objeto.
  • receiver_recurrence_id - Obrigatório. UUID da recorrência previamente autorizada que essa cobrança vai consumir.

curl --request POST \
     --url 'https://api.iugu.com/v1/invoices?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "due_date": "2026-05-17",
  "items": [
    {
      "description": "Mensalidade Serviço X - Maio",
      "quantity": 1,
      "price_cents": 100
    }
  ],
  "payable_with": [
    "pix"
  ],
  "payer": {
    "cpf_cnpj": "12345678910",
    "name": "Nome do Pagador"
  },
  "automatic_pix": {
    "receiver_recurrence_id": "UUID"
  }
}
'

{
  "id": "735D33684FAD432CAA89FC914EA8DBAB",
  "due_date": "2026-05-17",
  "currency": "BRL",
  "discount_cents": null,
  "email": "[email protected]",
  "items_total_cents": 100,
  "notification_url": null,
  "return_url": null,
  "status": "pending",
  "tax_cents": null,
  "total_cents": 100,
  "total_paid_cents": 0,
  "taxes_paid_cents": null,
  "paid_at": null,
  "paid_cents": null,
  "cc_emails": null,
  "financial_return_date": null,
  "payable_with": "pix", //Método de pagamento PIX
  (...)

 "automatic_pix": {
    "recurrence_receiver_payment": {
      "receiver_recurrence_payment_id": "0ed1b7c5-300c-4f02-bf3d-0f56535b1b07",
      "scheduled_payment_at": "2026-05-15T12:34:56-03:00",
      "receiver_recurrence_payment_end_to_end_id": "E151119752026051715002d6a893eccc"
    }

❗️

Importante

• O due_date da fatura será a data em que o débito automático será realizado na conta do pagador — e não a data em que a chamada à API foi feita.

Regras de Agendamento

Janela de Envio

A instrução de pagamento deve ser enviada entre 2 e 10 dias antes da data prevista de liquidação. Esse prazo é definido pelo BACEN.

• Mínimo (2 dias): antecedência necessária para o PSP do pagador processar a instrução.
• Máximo (10 dias): o agendamento não pode ultrapassar o início do próximo ciclo.

Ciclo

Período a que se refere uma cobrança recorrente, determinado pela periodicidade e pela data de início da recorrência.

Exemplo: recorrência mensal com primeiro pagamento em 30/12/2024:

• 30/dez/2024 → 29/jan/2025
• 30/jan/2025 → 27/fev/2025
• 28/fev/2025 → 29/mar/2025
• 30/mar/2025 → 29/abr/2025

Quando a data esperada não existe no mês (ex.: 30 de fevereiro), o ciclo é ajustado para o último dia existente — por isso fev/2025 fecha em 27/fev e o próximo ciclo já começa em 28/Fev.

Diagrama de Sequência