# Loan

The **Loan** entity is recovered from institutions that support this product. It represents a loan contracted by the user, including data like contract number, taxes, interest rates, warranties, installments, etc.

```json
{
  "id": "658f07f1-8349-44cc-9590-e10fe9337060",
  "itemId": "a9e42ebd-bddc-4d59-8895-140d8a809799",
  "contractNumber": "000000721792794",
  "ipocCode": "92792126019929279212650822221989319252576",
  "productName": "Credito Pessoal Consignado",
  "type": "CREDITO_PESSOAL_COM_CONSIGNACAO",
  "kind": "LOAN",
  "date": "2023-07-20T00:00:00.000Z",
  "contractDate": "2022-08-01T00:00:00.000Z",
  "disbursementDates": ["2018-01-15T00:00:00.000Z"],
  "settlementDate": "2018-01-15T00:00:00.000Z",
  "contractAmount": 50000,
  "currencyCode": "BRL",
  "dueDate": "2028-01-15T00:00:00.000Z",
  "installmentPeriodicity": "MONTHLY",
  "installmentPeriodicityAdditionalInfo": "",
  "firstInstallmentDueDate": "2018-02-15T00:00:00.000Z",
  "CET": 0.29,
  "amortizationScheduled": "SAC",
  "amortizationScheduledAdditionalInfo": "",
  "cnpjConsignee": "60.500.998/0001-35",
  "interestRates": [
    {
      "taxType": "EFFECTIVE",
      "interestRateType": "SIMPLE",
      "taxPeriodicity": "YEARLY",
      "calculation": "21/252",
      "referentialRateIndexerType": "PRE_FIXADO",
      "referentialRateIndexerSubType": "TJLP",
      "referentialRateIndexerAdditionalInfo": "",
      "preFixedRate": 0.6,
      "postFixedRate": 0.55,
      "additionalInfo": ""
    }
  ],
  "contractedFees": [
    {
      "name": "Administracao de Operacoes",
      "code": "ADM_OP",
      "chargeType": "UNIQUE",
      "charge": "MINIMUM",
      "amount": 5,
      "rate": 0
    }
  ],
  "contractedFinanceCharges": [
    {
      "type": "IOF_POR_ATRASO",
      "additionalInfo": "",
      "rate": 0.03
    }
  ],
  "warranties": [
    {
      "currencyCode": "BRL",
      "type": "SEM_TIPO_GARANTIA",
      "subtype": "ALIENACAO_FIDUCIARIA",
      "amount": 500
    }
  ],
  "installments": {
    "typeNumberOfInstallments": "MONTH",
    "totalNumberOfInstallments": 120,
    "typeContractRemaining": "MONTH",
    "contractRemainingNumber": 55,
    "paidInstallments": 65,
    "dueInstallments": 55,
    "pastDueInstallments": 0,
    "balloonPayments": []
  },
  "payments": {
    "contractOutstandingBalance": 25000,
    "releases": [
      {
        "isOverParcelPayment": false,
        "installmentId": "b1f0a5b4-1234-5678-9abc-def012345678",
        "paidDate": "2023-07-15T00:00:00.000Z",
        "currencyCode": "BRL",
        "paidAmount": 680.5,
        "overParcel": {
          "fees": [],
          "charges": []
        }
      }
    ]
  }
}
```

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `id` | `string` | No | Primary identifier |
| `itemId` | `string` | No | Identifier of the item linked to the loan |
| `contractNumber` | `string` | Yes | Contract number given by the contracting institution |
| `ipocCode` | `string` | Yes | Standard contract number - IPOC (Identificação Padronizada da Operação de Crédito) |
| `productName` | `string` | No | Denomination/Identification of the name of the credit operation disclosed to the customer |
| `type` | `string` | Yes | Loan type ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractProductSubTypeLoans)) |
| `kind` | `string` | No | Credit-operation family this contract belongs to. One of `LOAN`, `FINANCING`, `INVOICE_FINANCING`, `UNARRANGED_ACCOUNT_OVERDRAFT`. |
| `date` | `string` | No | Date when the loan data was collected |
| `contractDate` | `string` | Yes | Date when the loan was contracted |
| `disbursementDates` | `string[]` | Yes | Disbursement date of the contracted amount |
| `settlementDate` | `string` | Yes | Loan settlement date |
| `contractAmount` | `number` | Yes | Loan contracted value |
| `currencyCode` | `string` | No | Code referencing the currency of the loan |
| `dueDate` | `string` | Yes | Loan due date |
| `installmentPeriodicity` | `string` | Yes | Installments regular frequency. One of the [installment periodicity](#loan-installment-periodicity) values. |
| `installmentPeriodicityAdditionalInfo` | `string` | Yes | Mandatory field to complement the information regarding the regular payment frequency when installmentPeriodicity has value 'OTHERS' |
| `firstInstallmentDueDate` | `string` | Yes | First installment due date |
| `CET` | `number` | Yes | CET - Custo Efetivo Total must be expressed as an annual percentage rate and incorporates all charges and expenses incurred in credit operations (interest rate, but also tariffs, taxes, insurance and other expenses charged) |
| `amortizationScheduled` | `string` | Yes | Amortization system ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractAmortizationScheduled)). One of the [amortization system](#loan-amortization-system) values. |
| `amortizationScheduledAdditionalInfo` | `string` | Yes | Mandatory field to complement the information regarding the scheduled amortization when it has value 'OTHERS' |
| `cnpjConsignee` | `string` | Yes | Consignor CNPJ |
| `interestRates` | array of [LoanInterestRate](#loan-interest-rate) | Yes | Interest rates applied to the contract. |
| `contractedFees` | array of [LoanContractedFee](#loan-contracted-fee) | Yes | List that brings the information of the tariffs agreed in the contract. |
| `contractedFinanceCharges` | array of [LoanContractedFinanceCharge](#loan-contracted-finance-charge) | Yes | List that brings the charges agreed in the contract |
| `warranties` | array of [LoanWarranty](#loan-warranty) | Yes | Warranties that guarantee the credit operation. |
| `installments` | [LoanInstallments](#loan-installments) | Yes | Remaining term and installments of the operation. |
| `payments` | [LoanPayments](#loan-payments) | Yes | Loan contract payment data |

> See [Loan](/reference/loan) in our API reference for more information.

## Loan installment periodicity

Installments regular frequency

- `WITHOUT_REGULAR_PERIODICITY`
- `WEEKLY`
- `FORTNIGHTLY`
- `MONTHLY`
- `BIMONTHLY`
- `QUARTERLY`
- `SEMESTERLY`
- `YEARLY`
- `OTHERS`

## Loan amortization system

Amortization system ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractAmortizationScheduled))

- `SAC`
- `PRICE`
- `SAM`
- `WITHOUT_AMORTIZATION_SYSTEM`
- `OTHERS`

## Loan interest rate

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `taxType` | `string` | Yes | Tax type. One of the [tax type](#loan-tax-type) values. |
| `interestRateType` | `string` | Yes | Interest rate type. One of the [interest rate type](#loan-interest-rate-type) values. |
| `taxPeriodicity` | `string` | Yes | Tax periodicity. One of the [tax periodicity](#loan-tax-periodicity) values. |
| `calculation` | `string` | Yes | Calculation basis |
| `referentialRateIndexerType` | `string` | Yes | Types of benchmark rates or indexers ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractReferentialRateIndexerType)) |
| `referentialRateIndexerSubType` | `string` | Yes | Subtypes of benchmark rates or indexers ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractReferentialRateIndexerSubType)) |
| `referentialRateIndexerAdditionalInfo` | `string` | Yes | Free field to complement the information regarding the Type of reference rate or indexer |
| `preFixedRate` | `number` | Yes | Pre-fixed rate applied under the credit modality contract. 1 = 100% |
| `postFixedRate` | `number` | Yes | Post-fixed rate applied under the credit modality contract. 1 = 100% |
| `additionalInfo` | `string` | Yes | Text with additional information on the composition of agreed interest rates |

## Loan tax type

- `NOMINAL`
- `EFFECTIVE`

## Loan interest rate type

- `SIMPLE`
- `COMPOUND`

## Loan tax periodicity

- `MONTHLY`
- `YEARLY`

## Loan contracted fee

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | Agreed rate denomination |
| `code` | `string` | Yes | Acronym identifying the agreed rate |
| `chargeType` | `string` | Yes | Charge type for the rate agreed in the contract. One of the [charge type](#contracted-fee-charge-type) values. |
| `charge` | `string` | Yes | Billing method related to the tariff agreed in the contract. One of the [charge](#contracted-fee-charge) values. |
| `amount` | `number` | Yes | Monetary value of the tariff agreed in the contract |
| `rate` | `number` | Yes | Rate value in percentage agreed in the contract |

## Contracted fee charge type

Charge type for the rate agreed in the contract

- `UNIQUE`
- `BY_INSTALLMENT`

## Contracted fee charge

Billing method related to the tariff agreed in the contract

- `MINIMUM`
- `MAXIMUM`
- `FIXED`
- `PERCENTAGE`

## Loan contracted finance charge

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `type` | `string` | Yes | Charge type agreed in the contract ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractFinanceChargeType)) |
| `additionalInfo` | `string` | Yes | Field for additional information |
| `rate` | `number` | Yes | Charge value in percentage agreed in the contract |

## Loan warranty

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `currencyCode` | `string` | Yes | Code referencing the currency of the warranty |
| `type` | `string` | Yes | Denomination / Identification of the type of warranty that guarantees the Type of Credit Operation contracted ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumWarrantyType)) |
| `subtype` | `string` | Yes | Denomination / Identification of the subtype of warranty that guarantees the Type of Credit Operation contracted ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumWarrantySubType)) |
| `amount` | `number` | Yes | Warranty original value |

## Loan installments

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `typeNumberOfInstallments` | `string` | Yes | Type of total term of the contract referring to the type of credit informed. One of the [number of installments](#number-of-installments) values. |
| `totalNumberOfInstallments` | `number` | Yes | Total term according to the type referring to the type of credit informed |
| `typeContractRemaining` | `string` | Yes | Type of remaining term of the contract referring to the type of credit informed. One of the [type contract remaining](#type-contract-remaining) values. |
| `contractRemainingNumber` | `number` | Yes | Remaining term according to the type referring to the credit type informed |
| `paidInstallments` | `number` | Yes | Number of paid installments |
| `dueInstallments` | `number` | Yes | Number of due installments |
| `pastDueInstallments` | `number` | Yes | Number of overdue installments |
| `balloonPayments` | array of [LoanInstallmentBalloonPayment](#loan-balloon-payment) | Yes | List that brings the due dates and value of the non-regular installments of the contract of the type of credit consulted |

## Number of installments

Type of total term of the contract referring to the type of credit informed

- `DAY`
- `WEEK`
- `MONTH`
- `YEAR`
- `WITHOUT_TOTAL_PERIOD`

## Type contract remaining

Type of remaining term of the contract referring to the type of credit informed

- `DAY`
- `WEEK`
- `MONTH`
- `YEAR`
- `WITHOUT_TOTAL_PERIOD`
- `WITHOUT_REMAINING_PERIOD`

## Loan balloon payment

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `dueDate` | `string` | Yes | Expiration date of the non-regular installment to expire from the contract of the consulted credit modality |
| `amount` | [LoanInstallmentBalloonPaymentAmount](#balloon-payment-amount) | Yes |  |

## Balloon payment amount

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `value` | `number` | Yes | Monetary value of the non-regular installment due |
| `currencyCode` | `string` | Yes | Code referencing the currency of the installment |

## Loan payments

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `contractOutstandingBalance` | `number` | Yes | Amount required for the customer to settle the debt |
| `releases` | array of [LoanPaymentRelease](#loan-payment-release) | Yes | List of payments made in the period |

## Loan payment release

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `isOverParcelPayment` | `boolean` | Yes | Identifies whether it is an agreed payment (false) or a one-time payment (true) |
| `installmentId` | `string` | Yes | Installment identifier, responsibility of each transmitting Institution |
| `paidDate` | `string` | Yes | Effective date of payment referring to the contract of the credit modality consulted |
| `currencyCode` | `string` | Yes | Code referencing the currency of the payment |
| `paidAmount` | `number` | Yes | Payment amount referring to the contract of the credit modality consulted |
| `overParcel` | [LoanPaymentReleaseOverParcel](#loan-payment-over-parcel) | Yes |  |

## Loan payment over parcel

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `fees` | array of [LoanPaymentReleaseOverParcelFee](#over-parcel-fee) | Yes | List of fees that were paid outside the installment, only for single payment |
| `charges` | array of [LoanPaymentReleaseOverParcelCharge](#over-parcel-charge) | Yes | List of charges that were paid out of installment |

## Over parcel fee

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | Denomination of the agreed rate |
| `code` | `string` | Yes | Acronym identifying the agreed rate |
| `amount` | `number` | Yes | Monetary value of the tariff agreed in the contract |

## Over parcel charge

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `type` | `string` | Yes | Charge type agreed in the contract ([Open Finance definition](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractFinanceChargeType)) |
| `additionalInfo` | `string` | Yes | Free field to fill in additional information regarding the charge |
| `amount` | `number` | Yes | Payment amount of the charge paid outside the installment |