### Example Account Verification Request and Response

Source: https://dev.iugu.com/docs/configurar-subconta-por-api-copy

Provides an example of a POST request to the `/v1/accounts/account_id/request_verification` endpoint, including sample JSON data for account verification. It also shows the expected JSON response upon successful verification.

```curl
curl --request POST \
     --url 'https://api.iugu.com/v1/accounts/account_id/request_verification?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "price_range": "Até R$ 100,00",
    "physical_products": false,
    "business_type": "Meu negócio",
    "person_type": "Pessoa Jurídica",
    "automatic_transfer": false,
    "cnpj": "89814893000112",
    "company_name": "Minha empresa",
    "street": "Av. das Nações Unidas",
    "number": "12495",
    "district": "Cidade Monções",
    "cep": "04578-000",
    "city": "São Paulo",
    "state": "SP",
    "telephone": "5511971111111",
    "resp_name": "Nome do Resp",
    "resp_cpf": "736.858.020-97",
    "estimated_revenue": "100.00",
    "bank": "Itaú",
    "bank_ag": "9999",
    "account_type": "Corrente",
    "bank_cc": "999999999-D"
  }
}
'
```

```json
{
  "id": "FBB9275622CB4258A93A886C60B917EC",
  "data": {
    "price_range": "Até R$ 100,00",
    "physical_products": false,
    "business_type": "Meu negócio",
    "person_type": "Pessoa Jurídica",
    "automatic_transfer": false,
    "cep": "04578-000",
    "district": "Cidade Monções",
    "city": "São Paulo",
    "state": "SP",
    "street": "Av. das Nações Unidas",
    "number": "12495",
    "telephone": "5511971111111",
    "bank": "Itaú",
    "bank_ag": "9999",
    "account_type": "Corrente",
    "bank_cc": "999999999-D",
    "estimated_revenue": "100.00",
    "cnpj": "89814893000112",
    "company_name": "Minha empresa",
    "resp_name": "Nome do Resp",
    "resp_cpf": "736.858.020-97",
    "bank_ispb": "60701190"
  },
  "account_id": "FE2D01700CE3448C84B4DFD00049E1BC",
  "created_at": "2025-11-18T14:44:44-03:00"
}
```

--------------------------------

### Direct Charge API Request Example (Shell)

Source: https://dev.iugu.com/docs/realizar-uma-cobran%C3%A7a-simples-no-cart%C3%A3o-de-cr%C3%A9dito-por-api

This example demonstrates how to make a POST request to the `v1/charge` endpoint to perform a direct charge. It includes essential parameters such as payer information, a card token, and item details. The response indicates the transaction status and provides a URL for the invoice.

```shell
curl --request POST \
     --url 'https://api.iugu.com/v1/charge?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "payer": {
    "name": "Nome do Pagador",
    "cpf_cnpj": "113.436.750-30"
  },
  "token": "d2a133e0-280c-4401-8624-94cd84254ac5",
  "items": [
    {
      "description": "Descrição do Item",
      "quantity": 1,
      "price_cents": 5000
    }
  ],
  "email": "email@iugu.com"
}'
```

--------------------------------

### Setup Iugu.js for Usability Enhancements (JavaScript)

Source: https://dev.iugu.com/docs/tokenizacao-de-cartao-de-credito

Initializes the Iugu.js library, which is necessary for enabling automatic improvements to card input fields when Formatter.js is present. This setup is particularly important for web applications using frameworks like Backbone or Ember, and should be called on view rendering.

```javascript
Iugu.setup();
```

--------------------------------

### Example API Refund Response

Source: https://dev.iugu.com/docs/realizar-o-reembolso-de-faturas-estorno-por-api

This is a summarized example of a successful response after initiating an invoice refund via the Iugu API. It includes key details such as the refund ID, due date, currency, and the updated status of the invoice, which should reflect 'refunded'.

```json
{
  "id": "A123D06C9ADA54FBBA7C427C677886A41",
  "due_date": "2024-05-08",
  "currency": "BRL",
  "discount_cents": null,
  "email": "teste@iugu.com",
  "items_total_cents": 1000,
  "notification_url": null,
  "return_url": null,
  "status": "refunded", /// Reembolsada
  "tax_cents": null,
  "total_cents": 1000,
  ...
}
```

--------------------------------

### Iugu Setup

Source: https://dev.iugu.com/docs/tokenizacao-de-cartao-de-credito

Initializes Iugu.js, particularly useful in Single Page Applications (SPAs) or frameworks like Backbone/Ember to ensure usability enhancements are activated on view renders.

```APIDOC
## Iugu Setup

### Description
Initializes or re-initializes the Iugu.js library. This is recommended in dynamic web applications (like SPAs using Backbone, Ember, etc.) to ensure that usability enhancements, such as automatic input formatting with Formatter.js, are correctly applied whenever views are rendered.

### Method
JavaScript Function Call

### Endpoint
N/A (Client-side function)

### Parameters
None

### Request Example
```javascript
// Call this function when your application's views are rendered or updated
Iugu.setup();
```

### Response
No direct return value. It configures the Iugu.js library for subsequent operations.
```

--------------------------------

### Create PIX Invoice Request Example

Source: https://dev.iugu.com/docs/cdu-faturas

This example demonstrates how to create an invoice with PIX as the only accepted payment method using the Iugu API. It includes essential parameters like customer email, due date, items, and the 'payable_with' field set to 'pix'.

```bash
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@iugu.com",
  "due_date": "2024-05-27",
  "items": [
    {
      "description": "Item",
      "quantity": 1,
      "price_cents": 100
    }
  ],
  "payable_with": [
    "pix"
  ]
}
'
```

--------------------------------

### Create Invoice with Split Configuration (cURL)

Source: https://dev.iugu.com/docs/criar-cashback

This example demonstrates how to create an invoice using cURL, including a 'splits' array to define how the payment will be divided among recipients. This method overrides any pre-existing split configurations set in the Iugu Dashboard or via the accounts configuration endpoint.

```curl
curl --location --request POST 'https://api.iugu.com/v1/invoices' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=1b73fa0fcd5aaa5d72e58dee93da89e98d88de4a-1635344492' \
--data-raw '{ 
    "email": "customer.iugu@mailinator.com", 
    "due_date": "2021-10-28 ", 
    "items": [ 
        { 
            "description": "Item teste c/ cashback", 
            "quantity": 1, 
            "price_cents": 12000 
        } 
    ], 
    "customer_id": "B74B1779689E4684B02BD8D2867656F6", 
    "payable_with": [ 
        "credit_card" 
    ], 
    "splits": [ 
        { 
            "recipient_account_id": "{{account_id}}", 
            "percent": 10 
        } 
    ] 
}'
```

--------------------------------

### Create Iugu API Token with cURL

Source: https://dev.iugu.com/docs/tokens-de-autenticacao

This example demonstrates how to create an API token using cURL. It requires the API token for authentication and includes a request body with `api_type` and `description`. The response contains the newly created API token details.

```shell
curl --request POST \
     --url 'https://api.iugu.com/v1/27016E1AD888499A98994E781B6C3762/api_tokens?api_token=1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF' \
     --header 'Request-Time: 2025-03-12T14:58:01-03:00' \
     --header 'Signature: signature=nGDVNcBXfQ8kkGM2I/0XHDOOI0v6NCJCFzsm9TkZ3t1gihHDLUSpGY2/squfwxRMXpLBibdcMFH5ZS4xsadE7vuHnaJWYaXzsjMk9a5sM2kCPt1VAG4kmrRaToSoeXe6NrH96hASS1IXywzTPJJl/TbxV0i9uXzl0THRQ/BLSAmKZyEpATMdN5pWLFnohYfXjQ40w7W3Q4u/OzhWKGaGEOi9zkgqI89KHinci+7s90h/N8ttsmR+Ira8raWI6XMBKfbPuOYjuLKaZiNBce9+MkphRGFPlYw0uzSoiLzONtoCWoETrtPdMSKpSQQFU/yWMxIs/+Koav8jF2HsVcl/tg==' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "api_type": "LIVE",
  "description": "Meu token de produção"
}'
```

--------------------------------

### Create Subscription using cURL

Source: https://dev.iugu.com/docs/realizar-cobran%C3%A7as-recorrentes-por-api

This example shows how to create a subscription for a customer using a cURL request. It requires the customer ID and the plan identifier. Parameters like 'payable_with' and 'price_cents' can be inherited from the plan if not provided. Setting 'only_on_charge_success' to true ensures the subscription is created only if the initial charge is successful.

```shell
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": "7112C74C949A4195805265251C76ACF6",
  "plan_identifier": "dev_basic"
}'
```

--------------------------------

### Criar Fatura via API

Source: https://dev.iugu.com/docs/faturas-1

This section details how to create an invoice using the iugu API. It explains the endpoint, required parameters, and provides a practical example.

```APIDOC
## POST /v1/invoices

### Description
Creates an invoice (fatura) in iugu. Invoices are distinct from direct charges as they require explicit payment action from the customer and offer higher customization.

### Method
POST

### Endpoint
/v1/invoices

### Parameters
#### Query Parameters
None

#### Request Body
- **email** (string) - Required - The email address where the invoice will be sent.
- **due_date** (string) - Required - The due date for the invoice (e.g., YYYY-MM-DD).
- **payable_with** (string) - Required - Specifies the payment methods accepted. Accepts `bank_slip`, `credit_card`, `pix`, or `all`.
  - If `bank_slip` is selected, `payer.cpf_cnpj` and `payer.name` are also required.
- **items** (array of objects) - Required - An array of items included in the invoice. Each item object must contain:
  - **description** (string) - Required - Description of the item or service.
  - **quantity** (integer) - Required - The quantity of the item.
  - **price_cents** (integer) - Required - The price of the item in cents.

#### Payer Object (when `payable_with` includes `bank_slip`)
- **cpf_cnpj** (string) - Required - The CPF or CNPJ of the payer.
- **name** (string) - Required - The name of the payer.

### Request Example
```json
{
  "email": "cliente@email.com",
  "due_date": "2024-12-31",
  "payable_with": "all",
  "items": [
    {
      "description": "Serviço de consultoria",
      "quantity": 1,
      "price_cents": 50000
    }
  ],
  "payer": {
    "cpf_cnpj": "11111111111",
    "name": "Nome do Cliente"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created invoice.
- **due_date** (string) - The due date of the invoice.
- **items** (array) - Details of the items included in the invoice.
- **created_at** (string) - The timestamp when the invoice was created.
- **status** (string) - The current status of the invoice (e.g., 'pending', 'paid').
- **total** (integer) - The total amount of the invoice in cents.
- **paid_at** (string or null) - The timestamp when the invoice was paid, if applicable.

#### Response Example
```json
{
  "id": "inv_abcdef123456",
  "due_date": "2024-12-31",
  "items": [
    {
      "description": "Serviço de consultoria",
      "quantity": 1,
      "price_cents": 50000,
      "id": "item_xyz789"
    }
  ],
  "created_at": "2024-07-25T10:00:00Z",
  "status": "pending",
  "total": 50000,
  "paid_at": null,
  "url": "https://pay.iugu.com/inv_abcdef123456"
}
```

#### Error Response (400/422)
- **errors** (object) - An object containing error details.
  - **messages** (object) - Specific error messages keyed by field.

#### Error Response Example
```json
{
  "errors": {
    "messages": {
      "due_date": [
        "Data de vencimento inválida."
      ]
    }
  }
}
```
```

--------------------------------

### POST /charge - Process Installment Payment

Source: https://dev.iugu.com/docs/realizar-upgrade-de-plano-sem-cobrar-pro-rata-e-permitir-parcelamento

This endpoint allows you to process an installment payment for a subscription. It requires the customer's payment method ID, the invoice ID, and the number of installments.

```APIDOC
## POST /charge

### Description
This endpoint is used to process an installment payment for a subscription. It requires the customer's payment method ID, the invoice ID, and the number of installments.

### Method
POST

### Endpoint
https://api.iugu.com/v1/charge

### Parameters
#### Query Parameters
None

#### Request Body
- **customer_payment_method_id** (string) - Required - The ID of the customer's payment method.
- **invoice_id** (string) - Required - The ID of the invoice to be charged.
- **months** (integer) - Required - The number of installments.

### Request Example
```json
{
    "customer_payment_method_id": "{{id_forma_de_pagamento}}",
    "invoice_id": "6CD4B94FF6244DF8889608514525B742",
    "months": 2
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the charge.
- **invoice_id** (string) - The ID of the invoice.
- **status** (string) - The status of the charge.
- **amount** (string) - The amount charged.
- **installments** (integer) - The number of installments.

#### Response Example
```json
{
    "id": "CHARGE_ID_EXAMPLE",
    "invoice_id": "6CD4B94FF6244DF8889608514525B742",
    "status": "paid",
    "amount": "100.00",
    "installments": 2
}
```

### Notes
- To enable installment payments, your account must be configured for it in the iugu panel (Settings >> Credit Card >> Installments).
- For installment subscriptions, you must always call the direct charge API when a new invoice is generated. Enable the `invoice.created` trigger to receive notifications and capture the invoice ID for direct charge API calls.
- You can learn more about setting up triggers [here](https://dev.iugu.com/docs/gatilhos).
```

--------------------------------

### Enable Credit Card Payment

Source: https://dev.iugu.com/docs/habilitar-m%C3%A9todos-de-pagamento-via-api

Configure credit card payment options, including activation, installments, and descriptor, using the account configuration endpoint.

```APIDOC
## POST /v1/accounts/configuration

### Description
Enables and configures credit card payments for your account.

### Method
POST

### Endpoint
/v1/accounts/configuration

### Parameters
#### Request Body
- **credit_card** (object) - Required - Credit card payment configuration.
  - **active** (boolean) - Required - Set to `true` to enable credit card payments.
  - **soft_descriptor** (string) - Optional - Description to appear on the invoice (12-22 characters).
  - **installments** (integer) - Optional - Number of installments allowed.
  - **max_installments** (integer) - Optional - Maximum number of installments (1-12).
  - **max_installments_without_interest** (integer) - Optional - Maximum number of interest-free installments.
  - **two_step_transaction** (boolean) - Optional - Enables two-step transaction process.
  - **installments_pass_interest** (boolean) - Optional - Enables interest pass-through for installments (for older accounts).

### Request Example
```json
{
  "credit_card": {
    "active": true,
    "soft_descriptor": "My Store Name",
    "installments": 12,
    "max_installments_without_interest": 6,
    "two_step_transaction": true
  }
}
```

### Response
#### Success Response (200)
- **credit_card** (object) - Credit card payment configuration details.
  - **active** (boolean) - Indicates if credit card payments are active.
  - **soft_descriptor** (string) - The descriptor shown on invoices.
  - **installments** (integer) - The number of installments configured.
  - **max_installments** (integer) - The maximum number of installments.
  - **max_installments_without_interest** (integer) - The maximum number of interest-free installments.
  - **two_step_transaction** (boolean) - Indicates if two-step transactions are enabled.
  - **installments_pass_interest** (boolean) - Indicates if interest pass-through is enabled.

#### Response Example
```json
{
  "credit_card": {
    "active": true,
    "soft_descriptor": "My Store Name",
    "installments": 12,
    "max_installments": 12,
    "max_installments_without_interest": 6,
    "two_step_transaction": true,
    "installments_pass_interest": false
  }
}
```
```

--------------------------------

### Iugu API Account Verification Response Example

Source: https://dev.iugu.com/docs/configurar-subconta-por-api

Example JSON response from the Iugu API after a successful account verification request. It contains the ID of the verification request, the processed account data, the account ID, and the creation timestamp. This response confirms the submission and provides identifiers for future reference.

```json
{
  "id": "FBB9275622CB4258A93A886C60B917EC",
  "data": {
    "price_range": "Até R$ 100,00",
    "physical_products": false,
    "business_type": "Meu negócio",
    "person_type": "Pessoa Jurídica",
    "automatic_transfer": false,
    "cep": "04578-000",
    "district": "Cidade Monções",
    "city": "São Paulo",
    "state": "SP",
    "street": "Av. das Nações Unidas",
    "number": "12495",
    "telephone": "5511971111111",
    "bank": "Itaú",
    "bank_ag": "9999",
    "account_type": "Corrente",
    "bank_cc": "999999999-D",
    "estimated_revenue": "100.00",
    "cnpj": "89814893000112",
    "company_name": "Minha empresa",
    "resp_name": "Nome do Resp",
    "resp_cpf": "736.858.020-97",
    "bank_ispb": "60701190"
  },
  "account_id": "FE2D01700CE3448C84B4DFD00049E1BC",
  "created_at": "2025-11-18T14:44:44-03:00"
}

```

--------------------------------

### Iugu Invoice Creation Response (JSON)

Source: https://dev.iugu.com/docs/cashback-como-desconto

This is an example JSON response received after creating an invoice with the Iugu API. It includes details such as the invoice ID, due date, currency, and pricing information in cents. Notably, `items_total_cents` reflects the total after applying any item-level discounts.

```json
{
  "id": "1DD7941E517B49FFA028C77675CC4EBB",
  "due_date": "2024-05-20",
  "currency": "BRL",
  "discount_cents": null, 
  "email": "js@iugu.com",
  "items_total_cents": 7700,
  "notification_url": null,
  "return_url": null,
  "status": "pending",
  "tax_cents": null,
  "total_cents": 7700, 
  "total_paid_cents": 0,
  "taxes_paid_cents": null,
  "paid_at": null,
  "paid_cents": null,
...
```

--------------------------------

### Create Subscription with Payment Splits via API

Source: https://dev.iugu.com/docs/cobran%C3%A7a-recorrente-assinaturas

This example shows how to create a subscription and define payment splits using the Iugu API. The `splits` object in the request body allows specifying recipient account IDs and the amount in cents. This utilizes the POST /v1/subscriptions endpoint.

```powershell
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 '{ \
       "plan_identifier": "basic_plan", \
       "customer_id": "282BF13F9DBF4D3D8C5D344FEA370F78", \
       "splits": [ \
         { \
           "recipient_account_id": "account_id", \
           "cents": 45 \
         } \
       ] \
     }'
```

--------------------------------

### Iugu Subscription Features JSON Example

Source: https://dev.iugu.com/docs/emails-transacionais

This snippet shows the structure of the `subscription.features` variable in Iugu, which provides subscription functionalities in JSON format. It illustrates how features and their values can be represented.

```json
{
  ":feature": {
    ":name":'Feature',
    ":value":0
  }
}
```

--------------------------------

### Invoice Creation with Due Date and Expiration - Shell

Source: https://dev.iugu.com/docs/faturas-1

Example of creating an invoice using the Iugu API, specifying a due date, expiration date, and late payment fine. This allows for flexible payment terms, including grace periods and penalties.

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

--------------------------------

### Create PIX Invoice Response Example

Source: https://dev.iugu.com/docs/cdu-faturas

This is a summarized response from creating an invoice with PIX enabled. It shows the basic invoice details and confirms 'pix' as the payable method. The full response includes a 'pix' object with QR code details.

```json
{
  "id": "B894097671074A29A8CA966CC12A7992",
  "due_date": "2024-05-27",
  "currency": "BRL",
  "discount_cents": null,
  "email": "email@iugu.com",
  "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
  (...)
}
```

--------------------------------

### Create Subscription Plan via API - Shell

Source: https://dev.iugu.com/docs/cobran%C3%A7a-recorrente-assinaturas

This code snippet demonstrates how to create a new subscription plan using the Iugu API. It requires the plan's name, identifier, interval details, value in cents, accepted payment methods, and maximum installments. The API endpoint is POST /v1/plans.

```shell
curl --request POST \
     --url https://api.iugu.com/v1/plans \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "payable_with": [
    "pix"
  ],
  "name": "Plano Básico",
  "identifier": "basic_plan",
  "interval": 2,
  "interval_type": "months",
  "value_cents": 1000,
  "invoice_max_installments": 2
}'
```

--------------------------------

### GET /v1/customers/{customerId}

Source: https://dev.iugu.com/docs/compartilhar-forma-de-pagamento

Consulta os detalhes de um cliente existente na conta mestre. Essa informação é crucial para garantir que os dados do cliente sejam consistentes ao serem replicados ou consultados em subcontas.

```APIDOC
## GET /v1/customers/{customerId}

### Description
Consulta os detalhes de um cliente existente na conta mestre. Essa informação é crucial para garantir que os dados do cliente sejam consistentes ao serem replicados ou consultados em subcontas.

### Method
GET

### Endpoint
https://api.iugu.com/v1/customers/{{customer_id}}

### Parameters
#### Path Parameters
- **customerId** (string) - Required - O ID do cliente a ser consultado.

#### Header Parameters
- **Accept** (string) - Required - `application/json`
- **Content-Type** (string) - Required - `application/json`
- **Authorization** (string) - Required - `Basic {{api_token_conta_mestre in base64}}`

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **id** (string) - ID único do cliente.
- **name** (string) - Nome do cliente.
- **email** (string) - Email do cliente.
- **phone** (string) - Telefone do cliente.
- **phone_prefix** (string) - Prefixo do telefone.
- **cpf_cnpj** (string) - CPF ou CNPJ do cliente.
- **zip_code** (string) - CEP do cliente.
- **street** (string) - Rua.
- **number** (string) - Número.
- **complement** (string) - Complemento.
- **district** (string) - Bairro.
- **city** (string) - Cidade.
- **state** (string) - Estado.
- **created_at** (string) - Data de criação.
- **updated_at** (string) - Data de atualização.
- **cc_emails** (array) - Lista de emails de cópia.
- **custom_variables** (array) - Variáveis customizadas.
- **items** (array) - Itens associados ao cliente.
- **bank_accounts** (array) - Contas bancárias associadas.
- **payment_methods** (array) - Formas de pagamento associadas.

#### Response Example
(Response example not provided in the source text, refer to image: `consulta_customer_contaMestre.png`)
```

--------------------------------

### GET /v1/accounts/{id}

Source: https://dev.iugu.com/docs/configurar-subconta-por-api-copy

Retrieves detailed information about a specific account, including balances.

```APIDOC
## GET /v1/accounts/{id}

### Description
Retrieves comprehensive data for a specific account, such as Available Balance for Withdrawal and Receivables Balance.

### Method
GET

### Endpoint
/v1/accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the account to retrieve information for.

### Response
#### Success Response (200)
- **available_balance_for_withdrawal** (number) - The amount available for withdrawal.
- **receivables_balance** (number) - The balance of receivables.
*Other account-specific data may be included.*

#### Response Example
```json
{
  "id": "ACCOUNT_ID",
  "available_balance_for_withdrawal": 1500.75,
  "receivables_balance": 2500.50
}
```

### Related Endpoints
- **GET /v1/accounts/financial**: Retrieves financial statement data.
- **POST /v1/bank_verification**: Modifies the banking domicile.
```

--------------------------------

### Iugu API Invoice Response Example - JSON

Source: https://dev.iugu.com/docs/faturas-1

Example JSON response structure for listing invoices via the Iugu API. It includes invoice details, item information, and facet data for filtering and analysis of invoice statuses.

```json
{
  "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
}
{
  "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
}
```

--------------------------------

### GET /v1/invoices

Source: https://dev.iugu.com/docs/faturas-1

Lists invoices with options for filtering by creation date and invoice status. Supports pagination.

```APIDOC
## GET /v1/invoices

### Description
Lists invoices with options for filtering by creation date and invoice status. Supports pagination.

### Method
GET

### Endpoint
`/v1/invoices`

#### Query Parameters
- **created_at_from** (string) - Optional - Filter invoices created on or after this date (YYYY-MM-DD).
- **created_at_to** (string) - Optional - Filter invoices created on or before this date (YYYY-MM-DD).
- **status** (string) - Optional - Filter invoices by their status (e.g., 'paid', 'pending').
- **limit** (integer) - Optional - Number of invoices to return per page (default is 100).
- **offset** (integer) - Optional - Number of invoices to skip for pagination.

### Response
#### Success Response (200)
- Returns an array of invoice objects. The structure of each invoice object is similar to the response of the `GET /v1/invoices/{id}` endpoint.

#### Response Example
[
  {
    "id": "inv_abc123",
    "description": "Example Invoice",
    "amount_cents": 5000,
    "status": "paid",
    "created_at": "2024-09-15T10:00:00-03:00"
  }
]

### Notes
- Refer to [pagination documentation](https://dev.iugu.com/reference/pagina%C3%A7%C3%A3o) for more details on handling paginated results.
- Consider using [Iugu Triggers](https://dev.iugu.com/docs/gatilhos) instead of polling for status updates.
```

--------------------------------

### Iugu Subscription JSON Response Example

Source: https://dev.iugu.com/docs/alterar-assinatura-1

This JSON object represents a typical response when interacting with the Iugu API for subscription management. It details settings such as recurring payment status, two-step payment, expiration dates, and suspension flags.

```json
{
     "id": "40339131",
     "email": "teste@j.com",
     "test": false,
     "due_date": "2021-11-24",
     "is_paid": false,
     "total_price": "1000",
     "items": [
          {
               "id": "55620640",
               "description": "Plano Mensal",
               "price": 1000,
               "quantity": 1,
               "total": 1000
          }
     ],
     "customer": {
          "name": "Teste",
          "email": "teste@j.com",
          "custom_variables": [],
          "id": "16945268",
          "company_id": "28724714"
     },
     "status": "pending",
     "proforma_invoice": null,
     "proforma_invoice_url": null,
     "pdf": null,
     "url": "https://secure.iugu.com.br/upl/invoices/40339131/a4e000e6e7f476366113374e8210922f",
     "redirection_url": null,
     "payment_url": "https://secure.iugu.com.br/invoices/40339131/a4e000e6e7f476366113374e8210922f",
     "created_at": "2021-11-24T17:28:39.000Z",
     "updated_at": "2021-11-24T17:28:39.000Z",
     "due_at": "2021-11-24T23:59:59.000Z",
     "expires_at": "2021-11-29T00:00:00.000Z",
     "occurrences": 0,
     "financial_transaction_id": null,
     "method": null,
     "user_id": 2140201,
     "account_id": "28724714",
     "commission": null,
     "campaigns": [],
     "items_total": 1000,
     "charges": [],
     "discounts": [],
     "taxes": [],
     "ref": null,
     "order_id": null,
     "custom_variables": [],
     "is_multiple_payment_method": false,
     "bank_slip_return_label": null,
     "bank_slip_paid_message": null,
     "bank_slip_final_message": null,
     "bank_slip_url": null,
     "external_id": null,
     "require_charge_confirmation": false,
     "cc_emails": "",
     "ignore_due_email": false,
     "suspended": false,
     "skip_charge": false,
     "suspend_on_invoice_expired": true,
     "two_step": false,
     "recurrent": true
}
```

--------------------------------

### Zero Auth Response Example (JSON)

Source: https://dev.iugu.com/docs/zero-auth

This JSON object represents a typical response from the iugu Zero Auth API. It includes a 'code' for the transaction status, a 'message' describing the outcome, and a 'valid' field indicating whether the card is active (true) or not (false).

```json
{
    "zero_auth": {
        "code": "00",
        "message": "Authorized",
        "valid": true
    }
}
```

--------------------------------

### Webhook Setup for Transfer Status

Source: https://dev.iugu.com/docs/transfer%C3%AAncia-para-terceiros

Configures a webhook to receive notifications about changes in the transfer request status.

```APIDOC
## Webhook Setup for Transfer Status

### Description
Before initiating a transfer, set up a webhook to receive real-time notifications regarding the status changes of your transfer requests. This is crucial for monitoring the progress and outcome of each transfer.

### Method
POST

### Endpoint
https://api.iugu.com/v1/web_hooks

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event** (string) - Required - The event to subscribe to. For transfer status changes, use `transfer_request.status_changed`.
- **url** (string) - Required - The URL where you want to receive the webhook notifications.

### Request Example
```curl
curl --location --request POST 'https://api.iugu.com/v1/web_hooks' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{token_api in base 64}}' \
--header 'Cookie: __cfruid=fc514b6aab26d4dae534fbd0f8b0722c61a054da-1648512345' \
--data-raw '{
 "event": "transfer_request.status_changed",
 "url": "https://your-domain.com/webhook-receiver"
}'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the webhook.
- **event** (string) - The subscribed event.
- **url** (string) - The configured webhook URL.

#### Response Example
```json
{
  "id": "whk_a1b2c3d4e5f6",
  "event": "transfer_request.status_changed",
  "url": "https://your-domain.com/webhook-receiver"
}
```
```

--------------------------------

### Direct Charge with Two Credit Cards (Shell)

Source: https://dev.iugu.com/docs/cobranca-com-2-cartoes

This example demonstrates how to charge a customer using two credit cards directly via the Iugu API. It requires an API token, the invoice ID, and an array of credit card payment details, including tokens and amounts. The response includes the updated invoice status and transaction details for each card.

```shell
curl --request POST \
     --url https://api.iugu.com/v1/charge_two_credit_cards \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "api_token": "api_token",
  "invoiced_id": "1234567890ABCDEF1234567890ABCDEF",
  "iugu_credit_card_payment": [
    {
      "token": "Ac2a7578-41a5-4851-a9c2-6b302c75f37e",
      "amount": 500
    },
    {
      "token": "Bc2a7578-41a5-4851-a9c2-6b302c75f37e",
      "amount": 500
    }
  ]
}'
```

--------------------------------

### Simulate Advance

Source: https://dev.iugu.com/docs/realizar-antecipa%C3%A7%C3%A3o-de-parcelas-via-api

Simulates the advance of selected installments to show the estimated costs and received values before the actual transaction.

```APIDOC
## Simulate Advance

### Description
Simulates the advance of selected installments to show the estimated costs and received values before the actual transaction. This endpoint helps in understanding the financial implications of advancing payments.

### Method
POST

### Endpoint
/v1/financial_transaction_requests/advance_simulation?transactions={transaction_ids}

### Parameters
#### Path Parameters
- **transactions** (string) - Required - Comma-separated list of transaction IDs to simulate for advance.

#### Query Parameters
None

#### Request Body
None

### Request Example
```curl
curl --location --request POST 'https://api.iugu.com/v1/financial_transaction_requests/advance_simulation?transactions=33666790,33666791' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}'
```

### Response
#### Success Response (200)
Returns a simulation object detailing the taxes, advance fees, and the net amount to be received for the advanced installments.

#### Response Example
![Simulate Anticipation](https://files.readme.io/23735af-simula_antecipacao.png "simula_antecipacao.png")

*The `taxes` field refers to the transaction fee for card payments. The `advance_fee` represents the fee for advancing this installment. The `received_value` is the net amount that will be received after the advance process.*
```

--------------------------------

### Perform Partial Invoice Refund via API

Source: https://dev.iugu.com/docs/realizar-o-reembolso-de-faturas-estorno-por-api

This example shows how to perform a partial refund on an invoice. It utilizes the `partial_value_refund_cents` parameter within the request body to specify the amount to be refunded. The API token needs to be base64 encoded for authorization.

```curl
curl --location --request POST 'https://api.iugu.com/v1/invoices/id/refund' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--data-raw '{ 
     "partial_value_refund_cents": 1000 
}'
```

--------------------------------

### Advance Installments

Source: https://dev.iugu.com/docs/realizar-antecipa%C3%A7%C3%A3o-de-parcelas-via-api

Executes the advance of selected installments. The total value of the advanced installments is added to the available balance for withdrawal.

```APIDOC
## Advance Installments

### Description
Executes the advance of selected installments. After selecting the installments you wish to advance, this call sends all their identifiers. The sum of the values of these installments will be added to your available balance for withdrawal.

### Method
POST

### Endpoint
/v1/financial_transaction_requests/advance

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **transactions** (array) - Required - An array of transaction IDs for the installments to be advanced.

### Request Example
```curl
curl --location --request POST 'https://api.iugu.com/v1/financial_transaction_requests/advance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--data-raw '{ 
    "transactions": [33666790,33666791] 
}'
```

### Response
#### Success Response (200)
Returns a confirmation of the advance operation, indicating the successful transfer of funds to the available balance.

#### Response Example
![Advance Installments](https://files.readme.io/b3bbc66-antecipar_Parcelas.png "antecipar_Parcelas.png")
```

--------------------------------

### Configure Installment Options

Source: https://dev.iugu.com/docs/cc-configuracoes-extras

Enable or disable credit card installments and set the maximum number of installments allowed per transaction.

```APIDOC
## POST /v1/accounts/configuration

### Description
Configures account settings, including installment options for credit card payments.

### Method
POST

### Endpoint
/v1/accounts/configuration

### Parameters
#### Request Body
- **credit_card** (object) - Required - Object containing credit card specific configurations.
  - **installments** (boolean) - Optional - Whether installments are allowed.
  - **max_installments** (integer) - Optional - The maximum number of installments allowed (1-12).

### Request Example
```json
{
  "credit_card": {
    "installments": true,
    "max_installments": 12
  }
}
```

### Response
#### Success Response (200)
- **credit_card** (object) - Contains the updated credit card configuration.
  - **installments** (boolean) - Indicates if installments are enabled.
  - **max_installments** (integer) - The maximum number of installments allowed.

#### Response Example
```json
{
  "credit_card": {
    "installments": true,
    "max_installments": 12
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.