📘

O que você irá aprender com esse artigo?

• O que é PIX Automatico
• Configurar metodo de pagamento PIX (Ativação)
• Realizar cobrança de uma fatura com PIX Automático

O que é PIX Automático?

O PIX Automático permite que recebedores configurem cobranças recorrentes que são debitadas automaticamente da conta do pagador, mediante autorização prévia. Esse modelo é ideal para pagamentos periódicos, como assinaturas, mensalidades ou serviços recorrentes, permitindo que as cobranças sejam realizadas de forma automática após a autorização do pagador.

Uma vez autorizada a recorrência, as cobranças podem ser executadas conforme as condições definidas pelo recebedor, como valor e periodicidade, reduzindo a necessidade de interação manual do pagador a cada pagamento.

Esta API implementa o fluxo do Recebedor conforme especificação do Banco Central do Brasil (BACEN), permitindo a emissão de cobranças utilizando o PIX Automático.

❗️

Atenção

O gerenciamento da recorrência não é realizado por esta API. O recebedor deve possuir um motor de recorrência próprio, responsável por controlar a periodicidade das cobranças (como datas, valores e regras de cobrança).

1. Ativar PIX como método de pagamento

Antes de oferecer o PIX como método de pagamento, deve-se ativá-lo. Para isso, há duas formas:

1. Via Painel. Acesse alia.iugu.com > Configurações > Pix > marque a caixa de seleção "Ativo" > Salvar.
2. Via API. Utilize o endpoint Configurar Pagamentos Pix — v1/payments/pix com o parâmetro enable como true.

🚧

Importante

Certifique-se que a conta que fará a requisição esteja verificada. Saiba mais.

2. Cobrar com PIX Automático

Com o PIX ativado, 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.
• Dentro do objeto automatic_pix, existe o parâmetro journey, responsável por definir o tipo de jornada da cobrança automática. Atualmente, estão disponíveis duas opções:

Request exemplo

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-03-15",
  "items": [
    {
      "description": "Teste",
      "quantity": 1,
      "price_cents": 100
    }
  ],
  "payable_with": [
    "pix"
  ],
  "payer": {
    "cpf_cnpj": "12345678910",
    "name": "Teste Teste"
  },
  "automatic_pix": {
    "journey": 3, // Tipo de jornada: 3 ou 4
    "frequency": "monthly", // Frequência da recorrência
    "recurrence_beginning": "2026-03-07", // Data de início da recorrência. Deve ser uma data futura
    "contract_number": "Teste1", // Identificador do contrato. Máximo de 35 caracteres.
    "end_date": "2026-12-01" // Data de término da recorrência
  }
}
'

{
  "id": "A41E01B916BE4F738668C4C62EE4DD81",
  "due_date": "2026-03-06",
  "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": {
    "receiver_recurrence_id": "C2A7C349068B400E9EDABF3EEB5AE12F",
    "contract_number": "Teste1"
  },

 "pix": {
    "qrcode": "https://faturas.iugu.com/qr_code/a41e01b9-16be-4f73-8668-c4c62ee4dd81-27c4",
    "qrcode_text": "00020101021226840014br.gov.bcb.pix2562qr.iugu.com/public/payload/v2/A41E01B916BE4F738668C4C62EE4DD8152040000530398654041.005802BR5925IUGU INSTITUICAO DE PAGAM6006CIDADE62070503***80880014br.gov.bcb.pix2566qr.iugu.com/public/payload/v2/rec/C2A6C349068B400E9EDABF3EEB5AE13F63041111",
    "status": "qr_code_created",
    "payer_cpf_cnpj": null,
    "payer_name": null,
    "end_to_end_id": null,
    "end_to_end_refund_id": null,
    "account_number_last_digits": null
  }

👍

PIX copia e cola e QRCode

No objeto pix, é possível coletar a imagem e a linha digitável do QRCode pelas propriedades qrcode e qrcode_text, respectivamente.

Pagar com PIX Automático

Utilize os gatilhos abaixo para acompanhar os eventos relacionados à fatura e à autorização do Pix Automático.

👍

Gatilhos para esses eventos

Mudança de Status da Fatura — invoice.status_changed Enviado quando o status de uma Fatura é alterado.

Alteração de Autorização do Pix Automático — automatic_pix.authorization_changed
Enviado quando ocorre alguma alteração no status da autorização do Pix Automático.

Fatura Liberada — invoice.released Enviado quando o valor de uma fatura fica disponível para utilização.

Diagrama de Sequência