Caso de uso

“Quero cobrar meus clientes periodicamente, com intervalos específicos entre as cobranças, de forma automática via Pix, sem depender do pagador acessar e pagar manualmente a cada ciclo, e sem precisar chamar a API todo mês para gerar a cobrança.”

---

Recorrência na iugu

O processo de cobranças recorrentes envolve dois passos principais:

1. Criar Plano — v1/plans: são definidos os detalhes da cobrança, como periodicidade e produtos ou serviços associados.
2. Criar Assinatura — v1/subscriptions: gera cobranças automáticas para os clientes conforme as especificações do plano.

Métodos de Pagamento Compatíveis

Todos os métodos de pagamento são compatíveis com Assinaturas, porém com comportamentos diferentes.

Pix (comum)

O Pix ("pix") sem o objeto automatic_pix segue a mesma dinâmica do boleto: o cliente precisa acessar a fatura e pagar manualmente a cada ciclo, via QR Code ou código copia-e-cola.

Pix Automático

Já o Pix Automático (Pix Recorrente) elimina essa dependência: uma vez autorizada a recorrência pelo pagador junto ao BACEN, a iugu passa a debitar automaticamente cada ciclo, sem novo QR Code e sem ação do lojista. Esse é o foco deste artigo.

Sequência de Chamadas

O passo a passo a seguir simula:

• A contratação de uma assinatura mensal (a cada 1 mês) com débito automático via Pix
• Dados do cliente (nome, CPF/CNPJ, e-mail) já coletados previamente
• Nenhuma tokenização de cartão é necessária — o Pix Automático não utiliza forma de pagamento tokenizada

1. Criar Plano

Já tem um plano criado? Pule para a etapa 2. Se não, utilize o endpoint Criar Plano — v1/plans. Atente-se aos parâmetros:

• identifier— Identificador do Plano. Utilize-o como uma tag que identifica o plano.
• interval_type— Meses (months) ou Semanas (weeks).
• interval — Quantidade de intervalos de Meses ou Semanas. Deve ser compatível com a frequencyque será usada no Pix Automático (ver tabela abaixo).

Request exemplo:

curl --request POST \
     --url 'https://api.iugu.com/v1/plans?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "Plano Mensal Pix",
  "identifier": "pix_basic",
  "interval": 1,
  "interval_type": "months",
  "value_cents": 1000,
  "payable_with": [
    "pix"
  ]
}
'

Frequência (frequency) e Compatibilidade com o Plano

O valor informado no parâmetro frequency do objeto automatic_pix precisa ser compatível com o intervalo configurado no Plano (interval e interval_type):

2. Criar um Cliente

Já tem um cliente criado? Pule para a etapa 3. Se não, utilize o Criar Cliente — v1/customers. Preencha os parâmetros obrigatórios:

• email — E-mail do cliente.
• name — Nome do cliente.
• cpf_cnpj — CPF ou CNPJ do cliente.

Request exemplo:

curl --request POST \
     --url 'https://api.iugu.com/v1/customers?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "name": "Nome do Cliente",
  "cpf_cnpj": "12345678910"
}
'

3. Criar Assinatura com Pix Automático

Utilize o endpoint Criar Assinatura — v1/subscriptions. Diferente do fluxo com cartão, não há etapa de Criar Forma de Pagamento: em vez disso, inclua payable_with: "pix" e o objeto automatic_pix, composto pelos seguintes parâmetros:

• journey(int32) - Define o tipo de jornada da cobrança automática: 3 — QRCode com primeiro pagamento: cria a recorrência juntamente com a primeira cobrança imediata; 4 — QRCode com proposta de recorrência: gera um QRCode com a proposta de criação de recorrência para cobranças imediatas ou futuras (também usado na reautorização de recorrências expiradas).
• frequency(string) - Periodicidade das cobranças da recorrência (ex.: monthly). Deve ser compatível com o intervalo do Plano.
• recurrence_beginning (string, formato YYYY-MM-DD) - Data de início da recorrência. Deve ser uma data futura.
• contract_number(string) - Identificador do contrato. Máximo de 35 caracteres.
• end_date(string, formato YYYY-MM-DD) - Data de término da recorrência. Não encerra a Assinatura na iugu — os dois precisam ser alinhados manualmente pelo lojista.

Request exemplo:

curl --request POST \
     --url 'https://api.iugu.com/v1/subscriptions?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "282BF13F9DBF4D3D8C5D344FEA370F78",
  "plan_identifier": "pix_basic",
  "payable_with": "pix",
  "automatic_pix": {
    "journey": 3,
    "frequency": "monthly",
    "recurrence_beginning": "2026-08-10",
    "contract_number": "Contrato-0001",
    "end_date": "2027-08-10"
  }
}
'

Status inicial e autorização do pagador

A Assinatura é criada no estado padrão (active) e a primeira Fatura é gerada com status pending. A autorização da recorrência junto ao BACEN acontece de forma assíncrona: o pagador escaneia o QR Code composto no app do banco e autoriza a recorrência; somente após a autorização aceita o débito é processado — ambos acompanhados via gatilhos, e não pela resposta síncrona do POST.

Ciclagem Automática

A cada novo ciclo, a iugu gera automaticamente a próxima fatura, sem chamada do lojista. O comportamento depende do status da recorrência junto ao BACEN:

• Recorrência approved — a iugu agenda o débito diretamente na recorrência existente. Não é necessário novo QR Code.

• Sem recorrência ativa — a iugu cria uma nova recorrência via Jornada 3, com novo QR Code para o pagador autorizar.
• Recorrência expired ou created — a iugu solicita reautorização via Jornada 4.

Retry de Pagamento

Quando uma fatura com Pix Automático vence sem pagamento, é possível solicitar reagendamento manual via POST /v1/invoices/:id/reschedule_automatic_pix_payment, desde que a fatura esteja expired, a solicitação seja feita em até 7 dias após o vencimento, e a recorrência esteja approved. Limite: máximo de 3 retentativas por fatura.

Features Complementares

Suspender e Reativar Assinatura

● Ativar Assinatura — v1/subscriptions/{id}/activate
● Suspender Assinatura — v1/subscriptions/{id}/suspend (cancela a recorrência Pix Automático junto ao BACEN de forma assíncrona)

Alteração de Método de Pagamento

A troca é feita via PUT /v1/subscriptions/{id}. De Pix Automático para Cartão, a recorrência é cancelada de forma assíncrona. De Cartão para Pix Automático, a recorrência é registrada apenas na próxima geração de fatura. A atualização in-place dos parâmetros do automatic_pix (sem trocar de método) não é suportada.

Acompanhar via Gatilhos (Webhooks)

Como o Pix Automático é assíncrono em todas as suas etapas, é essencial acompanhar via gatilhos em vez de fazer polling na API:

• automatic_pix.authorization_changed — informa se o pagador autorizou, rejeitou ou deixou expirar a recorrência.
• automatic_pix.payment_changed — informa se o débito do ciclo foi agendado/confirmado ou rejeitado.
• automatic_pix.cancellation_changed — informa se o cancelamento da recorrência foi aceito pelo PSP Pagador.
• automatic_pix.payment_cancellation_changed — informa o cancelamento de um agendamento de débito individual.

Diferença entre Pix (comum) e Pix Automático em Assinaturas

Exemplo em diagrama de sequência