📘
Está procurando pela referência da API?
Clique aqui para conferir na íntegra todas as nossas APIs.

As Faturas (ou invoices) são como pedidos e os detalhes desses pedidos. Diferente da Charge, elas não são cobradas imediatamente. O pagador precisa acessá-la e, só então, pagá-la. Além disso, as invoices têm um nível de personalização de suas variáveis muito maior que a Cobrança Direta, por exemplo.

Entenda a Diferença entre Cobrança Direta e Fatura.

Criar

Para criar uma fatura na iugu, há duas formas:

1. Via Alia

Acesse alia.iugu.com > clique em Recebimento

Faturas > Nova > escolha o cliente (ou crie um novo) > Criar Fatura

Na tela Nova Fatura, preencha (campos com * são obrigatórios):

Campo	Descrição
Data de Vencimento	Data em que a fatura vencerá.
Descrição	1. Nome do item ou descrição do serviço. 2. Quantidade do item. 3. Preço do item
Desconto, juros e multa	Escolha se a fatura terá desconto, multa e/ou juros e porcentagem para cada um.
Métodos de Pagamento	Escolha quais métodos serão aceitos para pagá-la. 1. Pix 2. Cartão de Crédito 3. Boleto Bancário

Clique em Salvar.

2. Via API

Para criar uma invoice utilizando nossa API, siga estes passos:

📘
Observação
Como dito, as invoices têm inúmeras configurações personalizáveis, então, para fins didáticos, simplificamos o exemplo a seguir.

Utilize o endpoint Criar Fatura — POST /v1/invoices

Preencha os seguintes parâmetros (os com * são obrigatórios):

Parâmetro	Descrição
`email`*	Endereço de e-mail que a fatura será enviada.
`due_date`*	Data de vencimento.
`payable_with`*	`bank_slip`, `credit_card` , `bank_slip` ou `all` (que contempla todos os anteriores).
`payable_with` com `bank_slip`	Preencha também, pelo menos, os parâmetros `cpf_cnpj` e `name` do objeto `payer`.
`items`*	E seus parâmetros `description`, `quantity` e `price_cents`.

Faça a requisição.

Requisição exemplo

curl --request POST \
     --url https://api.iugu.com/v1/invoices \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "items": [
    {
      "description": "Descrição do Item",
      "quantity": 1,
      "price_cents": 3000
    }
  ],
  "payer": {
    "cpf_cnpj": "113.436.750-30",
    "name": "Nome do Pagador"
  },
  "email": "[email protected]",
  "due_date": "2024-09-16",
  "payable_with": [
    "all"
  ]
}
'

{
  "id": "C34C8435CE0A4F79BFE5020C9A7BE2F3",
  "due_date": "2024-09-16",
  "currency": "BRL",
  "discount_cents": null,
  "email": "[email protected]",
  "items_total_cents": 3000,
  "notification_url": null,
  "return_url": null,
  "status": "pending",
  "tax_cents": null,
  "total_cents": 3000,
  "total_paid_cents": 0,
  "taxes_paid_cents": null,
  "paid_at": null,
  "paid_cents": null,
  "cc_emails": null,
  "financial_return_date": null,
  "payable_with": "all",
  "overpaid_cents": null,
  "ignore_due_email": null,
  "ignore_canceled_email": null,
  "advance_fee_cents": null,
  "commission_cents": null,
  "early_payment_discount": false,
  "order_id": null,
  "updated_at": "2024-09-16T10:53:17-03:00",
  "credit_card_brand": null,
  "credit_card_bin": null,
  "credit_card_last_4": null,
  "credit_card_captured_at": null,
  "credit_card_tid": null,
  "external_reference": null,
  "max_installments_value": null,
  "payer_name": "Nome do Pagador",
  "payer_email": null,
  "payer_cpf_cnpj": "11343675030",
  "payer_phone": null,
  "payer_phone_prefix": null,
  "payer_address_zip_code": null,
  "payer_address_street": null,
  "payer_address_district": null,
  "payer_address_city": null,
  "payer_address_state": null,
  "payer_address_number": null,
  "payer_address_complement": null,
  "payer_address_country": null,
  "late_payment_fine": 0,
  "late_payment_fine_cents": null,
  "split_id": null,
  "external_payment_id": null,
  "external_payment_description": null,
  "payment_booklet_id": null,
  "subscription_id": null,
  "variables": [
    {
      "variable": "barcode_v1",
      "value": "40196984100000030002024260000000000000072933"
    },
    {
      "variable": "barcode_version",
      "value": "1"
    },
    {
      "variable": "payer.cpf_cnpj",
      "value": "11343675030"
    },
    {
      "variable": "payer.name",
      "value": "Nome do Pagador"
    },
    {
      "variable": "payment_data.transaction_number",
      "value": "726644242606514"
    }
  ],
  "custom_variables": [],
  "logs": [
    {
      "id": "10654E834A23449F8EE0BFCD036E8917",
      "description": "Email de Fatura enviado!",
      "notes": "Fatura enviada com sucesso para: [email protected]",
      "created_at": "16/09, 10:53"
    },
    {
      "id": "8DDEA4B2090A4154B3F75623208956DA",
      "description": "Fatura criada com sucesso!",
      "notes": "Fatura criada!",
      "created_at": "16/09, 10:53"
    }
  ],
  "credit_card_transaction": null,
  "account_id": "44C5DC6376804D1FA792CBCA382105C1",
  "bank_account_branch": "0001",
  "bank_account_number": "2739435-0",
  "account_name": "Nome da Conta",
  "secure_id": "c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153",
  "secure_url": "https://faturas.iugu.com/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153",
  "customer_id": null,
  "customer_ref": null,
  "customer_name": null,
  "user_id": null,
  "total": "R$ 30,00",
  "taxes_paid": "R$ 0,00",
  "total_paid": "R$ 0,00",
  "total_overpaid": "R$ 0,00",
  "total_refunded": "R$ 0,00",
  "commission": "R$ 0,00",
  "fines_on_occurrence_day": "R$ 0,00",
  "total_on_occurrence_day": "R$ 0,00",
  "fines_on_occurrence_day_cents": 0,
  "total_on_occurrence_day_cents": 0,
  "refunded_cents": 0,
  "remaining_captured_cents": 0,
  "advance_fee": null,
  "estimated_advance_fee": null,
  "paid": "R$ 0,00",
  "original_payment_id": null,
  "double_payment_id": null,
  "per_day_interest": false,
  "per_day_interest_value": null,
  "per_day_interest_cents": 0,
  "interest": null,
  "discount": null,
  "duplicated_invoice_id": null,
  "bank_slip_extra_due": 10,
  "created_at": "16/09, 10:53",
  "created_at_iso": "2024-09-16T10:53:17-03:00",
  "authorized_at": null,
  "authorized_at_iso": null,
  "expired_at": null,
  "expired_at_iso": null,
  "refunded_at": null,
  "refunded_at_iso": null,
  "canceled_at": null,
  "canceled_at_iso": null,
  "protested_at": null,
  "protested_at_iso": null,
  "chargeback_at": null,
  "chargeback_at_iso": null,
  "occurrence_date": null,
  "refundable": null,
  "installments": null,
  "transaction_number": 726644242606514,
  "payment_method": null,
  "financial_return_dates": null,
  "bank_slip": {
    "digitable_line": "40192024256000000000400000729335698410000003000",
    "barcode_data": "40196984100000030002024260000000000000072933",
    "barcode": "https://api.iugu.com/v1/public/invoice/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153/barcode",
    "bank_slip_url": "https://boletos.iugu.com/v1/public/invoice/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153/bank_slip",
    "bank_slip_pdf_url": "https://boletos.iugu.com/v1/public/invoice/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153/bank_slip.pdf",
    "bank_slip_bank": 401,
    "bank_slip_status": "pending",
    "bank_slip_error_code": null,
    "bank_slip_error_message": null,
    "recipient_cpf_cnpj": "113.436.750-30"
  },
  "pix": {
    "qrcode": "https://faturas.iugu.com/qr_code/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153",
    "qrcode_text": "00020101021226840014br.gov.bcb.pix2562qr.iugu.com/public/payload/v2/C34C8435CE0A4F79BFE5020C9A7BE2F3520400005303986540530.005802BR5924KARTHEN JUNIOR RODRIGUES6009SAO PAULO62070503***630479A8",
    "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
  },
  "items": [
    {
      "id": "1F9F8BD291444FEDABE30FB750DCEFD7",
      "description": "Descrição do Item",
      "price_cents": 3000,
      "quantity": 1,
      "created_at": "2024-09-16T10:53:17-03:00",
      "updated_at": "2024-09-16T10:53:17-03:00",
      "price": "R$ 30,00"
    }
  ],
  "early_payment_discounts": [],
  "split_rules": null
}

🤔
Onde acessá-la?
A fatura é enviada para o e-mail do cliente, então, o pagador deve acessá-lo e clicar no botão "Pagar a Fatura".

Importante ⚠️ — Tarifas do Checkout iugu

Quando o pagador acessa o link checkout.iugu.com, é cobrado uma tarifa. Se deseja evitá-la, é necessário criar o seu próprio checkout. Saiba mais sobre Checkout Transparente e Checkout iugu.

Consulte também nossas tarifas em iugu.com/planos.

Consultar

Há duas formas de consultar as Faturas na iugu:

1. Via Alia

Com o ID da Fatura > clique em Recebimento
No campo de pesquisa > insira o ID e aperte Enter

Campo de pesquisa de faturas (elastic search) do Alia
Ao lado direito, clique em Ver para visualizar os detalhes da fatura e, inclusive, ter acesso ao link que redireciona para o checkout (secure_url).

2. Via API

Existem 2 endpoints que retornam detalhes de faturas:

Nome	Endpoint	Descrição
Consultar Fatura	`GET` `/v1/invoices/{id}`	Retorna detalhes de uma fatura específica.
Listar/Buscar Faturas	`GET` `/v1/invoices`	Listagem de 100 invoices por página. Com possibilidade de filtros de "criado em" à "status da fatura". Saiba mais sobre paginação. Conheça os nossos Gatilhos ao invés de realizar pooling.

Consultar Fatura — `/v1/invoices/{id}`

Response exemplo

{
  "id": "16F7AA3D2E0B41E9987B1DC95B957456",
  "due_date": "2024-07-16",
  "currency": "BRL",
  "discount_cents": null,
  "email": "[email protected]",
  "items_total_cents": 3000,
  "notification_url": null,
  "return_url": null,
  "status": "pending",
  "tax_cents": null,
  "total_cents": 3000,
  "total_paid_cents": 0,
  "taxes_paid_cents": null,
  "paid_at": null,
  "paid_cents": null,
  "cc_emails": null,
  "financial_return_date": null,
  "payable_with": "all",
  "overpaid_cents": null,
  "ignore_due_email": null,
  "ignore_canceled_email": null,
  "advance_fee_cents": null,
  "commission_cents": null,
  "early_payment_discount": false,
  "order_id": null,
  "updated_at": "2024-07-16T16:35:49-03:00",
  "credit_card_brand": null,
  "credit_card_bin": null,
  "credit_card_last_4": null,
  "credit_card_captured_at": null,
  "credit_card_tid": null,
  "external_reference": null,
  "max_installments_value": null,
  "payer_name": "Nome",
  "payer_email": null,
  "payer_cpf_cnpj": "11343675030",
  "payer_phone": null,
  "payer_phone_prefix": null,
  "payer_address_zip_code": null,
  "payer_address_street": null,
  "payer_address_district": null,
  "payer_address_city": null,
  "payer_address_state": null,
  "payer_address_number": null,
  "payer_address_complement": null,
  "payer_address_country": null,
  "late_payment_fine": 1,
  "late_payment_fine_cents": null,
  "split_id": null,
  "external_payment_id": null,
  "external_payment_description": null,
  "payment_booklet_id": null,
  "subscription_id": null,
  "variables": [
    {
      "variable": "barcode_v1",
      "value": "40195977900000030002024198000000000000165649"
    },
    {
      "variable": "barcode_version",
      "value": "1"
    },
    {
      "variable": "payer.cpf_cnpj",
      "value": "11343675030"
    },
    {
      "variable": "payer.name",
      "value": "Nome"
    },
    {
      "variable": "payment_data.transaction_number",
      "value": "375641241984723"
    }
  ],
  "custom_variables": [],
  "logs": [
    {
      "id": "0C7750D2CFEE44F187910416FE7E1661",
      "description": "Email de Fatura enviado!",
      "notes": "Fatura enviada com sucesso para: [email protected]",
      "created_at": "16/07, 16:34"
    },
    {
      "id": "F2A2A91E829245BFA72D1DE6244D2374",
      "description": "Fatura criada com sucesso!",
      "notes": "Fatura criada!",
      "created_at": "16/07, 16:34"
    }
  ],
  "credit_card_transaction": null,
  "account_id": "27016E1AD888499A98994E781B6C3762",
  "bank_account_branch": "0001",
  "bank_account_number": "3693443-0",
  "account_name": "Nome da Conta",
  "secure_id": "16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2",
  "secure_url": "https://checkout.iugu.com/invoices/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2",
  "customer_id": null,
  "customer_ref": null,
  "customer_name": null,
  "user_id": null,
  "total": "R$ 30,00",
  "taxes_paid": "R$ 0,00",
  "total_paid": "R$ 0,00",
  "total_overpaid": "R$ 0,00",
  "total_refunded": "R$ 0,00",
  "commission": "R$ 0,00",
  "fines_on_occurrence_day": "R$ 0,00",
  "total_on_occurrence_day": "R$ 0,00",
  "fines_on_occurrence_day_cents": 0,
  "total_on_occurrence_day_cents": 0,
  "refunded_cents": 0,
  "remaining_captured_cents": 0,
  "advance_fee": null,
  "estimated_advance_fee": null,
  "paid": "R$ 0,00",
  "original_payment_id": null,
  "double_payment_id": null,
  "per_day_interest": false,
  "per_day_interest_value": null,
  "per_day_interest_cents": 0,
  "interest": null,
  "discount": null,
  "duplicated_invoice_id": null,
  "bank_slip_extra_due": 2,
  "created_at": "16/07, 16:34",
  "created_at_iso": "2024-07-16T16:34:53-03:00",
  "authorized_at": null,
  "authorized_at_iso": null,
  "expired_at": null,
  "expired_at_iso": null,
  "refunded_at": null,
  "refunded_at_iso": null,
  "canceled_at": null,
  "canceled_at_iso": null,
  "protested_at": null,
  "protested_at_iso": null,
  "chargeback_at": null,
  "chargeback_at_iso": null,
  "occurrence_date": null,
  "refundable": null,
  "installments": null,
  "transaction_number": 375641241984723,
  "payment_method": null,
  "financial_return_dates": null,
  "bank_slip": {
    "digitable_line": "40192024179800000000400001656495597790000003000",
    "barcode_data": "40195977900000030002024198000000000000165649",
    "barcode": "https://api.iugu.com/v1/public/invoice/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2/barcode",
    "bank_slip_url": "https://boletos.iugu.com/v1/public/invoice/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2/bank_slip",
    "bank_slip_bank": 401,
    "bank_slip_status": "registered",
    "bank_slip_error_code": null,
    "bank_slip_error_message": null,
    "recipient_cpf_cnpj": "113.436.750-30"
  },
  "pix": {
    "qrcode": "https://faturas.iugu.com/qr_code/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2",
    "qrcode_text": "00020101021226840014br.gov.bcb.pix2562qr.iugu.com/public/payload/v2/16F7AA3D2E0B41E9987B1DC95B957456520400005303986540530.005802BR5925IUGU INSTITUICAO DE PAGAM6009SAO PAULO62070503***630446D8",
    "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
  },
  "items": [
    {
      "id": "0F30A8B1ED244325BBC6C8A1AE34AE18",
      "description": "Item",
      "price_cents": 3000,
      "quantity": 1,
      "created_at": "2024-07-16T16:34:53-03:00",
      "updated_at": "2024-07-16T16:34:53-03:00",
      "price": "R$ 30,00"
    }
  ],
  "early_payment_discounts": [],
  "split_rules": null
}

Listar/Buscar Fatura — `/v1/invoices`

Response exemplo

{
  "items": [
    {
     /Detalhes de uma Fatura (assim como o exemplo acima)
    }
  ],
  "facets": {
    "late": {
      "_type": "filter",
      "count": 60
    },
    "status": {
      "_type": "terms",
      "missing": 0,
      "other": 163,
      "terms": [
        {
          "term": "pending",
          "count": 125
        }
      ],
      "total": 125
    }
  },
  "totalItems": 288
}

Prazo de Expiração e Data de Vencimento

Data de Expiração e Data de Vencimento de uma Fatura podem ser confusas se não compreendermos a finalidade de cada um. Então, vamos por partes.

Data de Vencimento (`due_date`)

A data de vencimento é utilizada, em sua grande maioria, quando o modelo de negócio incide multas quando a data é ultrapassada e ainda não foi paga.

👍
Dica (API)💡
Utilize o parâmetro expired_url para redirecionar o pagador para o endereço web que desejar, seja com instruções de como reemitir a fatura ou o que sua criatividade quiser 😉.

Data de Expiração (`expires_in`)

Já a data de expiração é a data limite para pagar a invoice, mesmo que ela tenha ultrapassado a data de vencimento (due_date). Quando a fatura assume o status expired, não é possível pagá-la, obrigando sua reemissão.

Como combiná-los (sugestão)?

Cenário

"Gostaria que a fatura tivesse o vencimento no dia 26/09, mas permanecesse disponível por mais 4 dias, permitindo que o cliente a pague mesmo após o vencimento. Se o pagamento ocorrer entre os dias 27 e 30, deve ser aplicada uma multa de 2% sobre o valor total da fatura."

Para este cenário, durante a criação de uma Fatura, defina a Data de Vencimento menor que a Data de Expiração. Então, na prática (API):

{
  "due_date": "2024-09-26",
  "expires_in": "2024-09-30",
  "fines": true,
  "late_payment_fine": 2
}

Faturas

📘
Está procurando pela referência da API?

Criar

1. Via Alia

2. Via API

📘
Observação

Requisição exemplo

🤔
Onde acessá-la?

Importante ⚠️ — Tarifas do Checkout iugu

Consultar

1. Via Alia

2. Via API

Consultar Fatura — `/v1/invoices/{id}`

Response exemplo

Listar/Buscar Fatura — `/v1/invoices`

Response exemplo

Prazo de Expiração e Data de Vencimento

Data de Vencimento (`due_date`)

👍
Dica (API)💡

Data de Expiração (`expires_in`)

Como combiná-los (sugestão)?

📘Está procurando pela referência da API?

Criar

1. Via Alia

2. Via API

📘Observação

Requisição exemplo

🤔Onde acessá-la?

Importante ⚠️ — Tarifas do Checkout iugu

Consultar

1. Via Alia

2. Via API

Consultar Fatura — /v1/invoices/{id}

Response exemplo

Listar/Buscar Fatura — /v1/invoices

Response exemplo

Prazo de Expiração e Data de Vencimento

Data de Vencimento (due_date)

👍Dica (API)💡

Data de Expiração (expires_in)

Como combiná-los (sugestão)?

📘
Está procurando pela referência da API?

📘
Observação

🤔
Onde acessá-la?

Consultar Fatura — `/v1/invoices/{id}`

Listar/Buscar Fatura — `/v1/invoices`

Data de Vencimento (`due_date`)

👍
Dica (API)💡

Data de Expiração (`expires_in`)