> For the complete documentation index, see [llms.txt](https://midatechnologies.gitbook.io/mida-developer-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://midatechnologies.gitbook.io/mida-developer-portal/midaforms/loan-products.md).

# Loan products

## Create a loan product

#### Field description

<table><thead><tr><th width="49">#</th><th>Field</th><th width="296">Description</th><th width="142">Type</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>1</td><td>name</td><td>Product display name</td><td>string</td><td>false</td></tr><tr><td>2</td><td>type</td><td>Product type (FIXED_TERM_LOAN or INTEREST_FREE_TERM_LOAN)</td><td>enum</td><td>false</td></tr><tr><td>3</td><td>description</td><td>Product description </td><td>string</td><td>false</td></tr><tr><td>4</td><td>userType</td><td>Type of user (CLIENTS, COMPANIES)</td><td>enum</td><td>false</td></tr><tr><td>5</td><td>minAmount</td><td>Minimum product loan amount (in major)</td><td>decimal</td><td>false</td></tr><tr><td>6</td><td>maxAmount</td><td>maxium product loan amount (in major)</td><td>decimal</td><td>false</td></tr><tr><td>7</td><td>interest</td><td>Interest configuration (sub-fields below)</td><td>object</td><td>false</td></tr><tr><td>8</td><td>scheduling</td><td>Repayment scheduling (sub-fields below)</td><td>object</td><td>false</td></tr><tr><td>9</td><td>collection</td><td>Collection and prepayment rules</td><td>object</td><td>false</td></tr><tr><td>10</td><td>penalty</td><td>Penalty configuration</td><td>object</td><td>true</td></tr><tr><td>11</td><td>fees</td><td>Fees definitions</td><td>array(object)</td><td>true</td></tr></tbody></table>

#### Interest

<table><thead><tr><th width="48">#</th><th width="168">Field</th><th width="288">Description</th><th width="108">Type</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>1</td><td>daysInAYear</td><td>Day-count convention for interest calculations. 365 = actual/365 fixed; 360 = 30/360.</td><td>enum</td><td>false</td></tr><tr><td>2</td><td>interestType</td><td>Simple = interest on principal only; compound = interest on principal + accrued interest.</td><td>enum</td><td>false</td></tr><tr><td>3</td><td>interestCharged</td><td>The time period the interest rate applies to. (%_PER_WEEK, %_PER_MONTH, %_PER_YEAR)</td><td>enum</td><td>false</td></tr><tr><td>4</td><td>interestPosting</td><td>How interest is calculated. FLAT = fixed amount on original principal; DECLINING_BALANCE = interest on remaining balance.</td><td>enum</td><td>false</td></tr><tr><td>5</td><td>maxInterestRate</td><td>Highest interest rate allowed. Must be ≥ defaultInterestRate.</td><td>enum</td><td>false</td></tr><tr><td>6</td><td>minInterestRate</td><td>Lowest interest rate allowed when creating/editing a loan. Must be ≤ defaultInterestRate.</td><td>decimal</td><td>false</td></tr><tr><td>7</td><td>repaymentInterest</td><td>Basis for interest per repayment by repayment period or by number of days. (REPAYMENT_PERIOD, NUMBER_OF_DAYS)</td><td>enum</td><td>false</td></tr><tr><td>8</td><td>defaultInterestRate</td><td>Default interest rate applied to loans under this product. </td><td>decimal</td><td>false</td></tr><tr><td>9</td><td>interestCalculation</td><td>How interest is calculated. FLAT = fixed amount on original principal; DECLINING_BALANCE = interest on remaining balance.</td><td>enuum</td><td>false</td></tr></tbody></table>

#### Scheduling

<table><thead><tr><th width="47">#</th><th width="173">Field</th><th width="257">Description</th><th width="145">Type</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>1</td><td>paymentMade</td><td>Numeric value for the payment frequency (e.g. every 2 weeks).</td><td>object
<br>(value, peroid)</td><td>false</td></tr><tr><td>2</td><td>paymentMethod</td><td>Repayment structure. Standard = equal installments; balloon = smaller payments with a large final payment.(STANDARD_PAYMENT, BALLON_PAYMENT)</td><td>enum</td><td>true</td></tr><tr><td>3</td><td>maxInstallments</td><td>Maximum installments allowed. Must be ≥ defaultInstallments.</td><td>integer</td><td>false</td></tr><tr><td>4</td><td>minInstallments</td><td>Minimum installments allowed. Must be ≤ defaultInstallments.</td><td>integer</td><td>false</td></tr><tr><td>5</td><td>paymentInterval</td><td>When repayments fall due — on a fixed interval or at end of month. (INTERVAL, END_OF_MONTH)</td><td>enum</td><td>false</td></tr><tr><td>6</td><td>maxDueDateOffset</td><td>Maximum days after disbursement before the first repayment is due. Must be ≥ defaultDueDateOffset.</td><td>integer</td><td>false</td></tr><tr><td>7</td><td>minDueDateOffset</td><td>Minimum days after disbursement before the first repayment is due. Must be ≤ defaultDueDateOffset.</td><td>integer</td><td>false</td></tr><tr><td>8</td><td>defaultInstallments</td><td>Default number of repayment installments for a loan.</td><td>integer</td><td>false</td></tr><tr><td>9</td><td>currencyRoundingSchedule</td><td>How currency amounts are rounded in the repayment schedule (NO_ROUNDING, TO_NEAREST_WHOLE_UNIT, UP_TO_NEAREST_WHOLE_UNIT)</td><td>enum</td><td>true</td></tr><tr><td>10</td><td>principalRoundingSchedule</td><td>How leftover principal from rounding is handled across installments (NO_ROUNDING, PRINCIPAL_REMAINDER_TO_LAST_REPAYMENT, PRINCIPAL_REMAINDER_WITH_INTEREST_TO_LAST_REPAYMENT)</td><td>enum</td><td>true</td></tr><tr><td>11</td><td>maxGracePeriod</td><td>Maximum grace period (days). Must be ≥ defaultGracePeriod.</td><td>integer</td><td>true</td></tr><tr><td>12</td><td>minGracePeriod</td><td>Minimum grace period (days) before repayments start. Must be ≤ defaultGracePeriod.</td><td>integer</td><td>true</td></tr><tr><td>13</td><td>enableGracePeriod</td><td>Whether a grace period before repayments is allowed.</td><td>boolean</td><td>true</td></tr><tr><td>14</td><td>defaultGracePeriod</td><td>Default grace period in days. Required in practice when grace period is enabled.</td><td>integer</td><td>true</td></tr></tbody></table>

#### Collection

<table><thead><tr><th width="46">#</th><th width="174">Field</th><th width="309">Description</th><th width="90">Type</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>1</td><td>acceptPrepayment</td><td>Whether borrowers can pay before the due date. If false, repayments before the next scheduled due date are rejected.</td><td>boolean</td><td>false</td></tr><tr><td>2</td><td>paymentAllocation</td><td>How payments are applied across installments. HORIZONTAL = pay each installment fully before moving to the next. VERTICAL = pay one component (e.g. all principal) across installments before moving to the next component. (HORIZONTAL, VERTICAL)</td><td>enum</td><td>true</td></tr><tr><td>3</td><td>prepaymentAllocationOrder</td><td>Priority order for applying payment across components. Lower number = paid first.</td><td>object { fee, penalty, interest, principal }</td><td>true</td></tr></tbody></table>

#### Fees

<table><thead><tr><th width="44">#</th><th width="122">Field</th><th width="320">Description</th><th>Type</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>1</td><td>value</td><td>The fee amount. For FLAT = fixed amount; for PERCENTAGE_0F_DISBURSE_AMOUNT and percentage-based calculations = percentage value (e.g. 2.5 = 2.5%).</td><td>decimal</td><td>false</td></tr><tr><td>2</td><td>feeName</td><td>Label for the fee (e.g. "Processing Fee", "Admin Fee").</td><td>string</td><td>false</td></tr><tr><td>3</td><td>feeType</td><td>When the fee is charged. (ON_DISBURSEMENT, ON_PRE_LIQUIDATION, ONE_OFF_ON_FIRST_REPAYMENT, ON_EVERY_REPAYMENT)</td><td>enum</td><td>false</td></tr><tr><td>4</td><td>feePayment</td><td>Used specifically for ON_PRE_LIQUIDATION fees calculated on principal balance. (FLAT, PERCENTAGE_0F_DISBURSE_AMOUNT, PRINCIPAL, INTEREST, PRINCIPAL_AND_INTEREST)</td><td>enum</td><td>false</td></tr></tbody></table>

#### Penalty

<table><thead><tr><th width="45">#</th><th width="209">Field</th><th width="276">Description</th><th width="90">Type</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>1</td><td>enablePenalty</td><td>Whether late-payment penalties are applied to overdue loans.</td><td>boolean</td><td>false</td></tr><tr><td>2</td><td>penaltyTolerancePeriod</td><td>Grace period in days after the due date before penalties start accruing.</td><td>integer</td><td>true</td></tr><tr><td>3</td><td>defaultPenaltyRate</td><td>Default penalty rate (percentage) applied to overdue amounts.</td><td>decimal</td><td>true</td></tr><tr><td>4</td><td>minPenaltyRate</td><td>Minimum allowed penalty rate. Must be ≤ defaultPenaltyRate.</td><td>decimal</td><td>true</td></tr><tr><td>5</td><td>maxPenaltyRate</td><td>Maximum allowed penalty rate. Must be ≥ defaultPenaltyRate.</td><td>decimal</td><td>true</td></tr></tbody></table>

#### Security

The API security is a bearer token using your organisation's API Key obtained [here](https://collect.getmida.com/)

#### API Url

```
POST {base url}/integrations/v1/loan-products
```

#### Sample request

```
{
  "name": "Personal Loan",
  "type": "FIXED_TERM_LOAN",
  "description": "Short-term personal loan product",
  "userType": ["CLIENTS"],
  "minAmount": 10000,
  "maxAmount": 500000,
  "interest": {
    "daysInAYear": 365,
    "interestType": "FIXED",
    "interestCharged": "DAILY",
    "interestPosting": "END_OF_PERIOD",
    "maxInterestRate": 30,
    "minInterestRate": 5,
    "repaymentInterest": "EQUAL",
    "defaultInterestRate": 15,
    "interestCalculation": "DECLINING_BALANCE"
  },
  "scheduling": {
    "paymentMade": { "value": 1, "period": "MONTH" },
    "paymentMethod": "STANDARD_PAYMENT",
    "maxGracePeriod": 7,
    "minGracePeriod": 0,
    "maxInstallments": 12,
    "minInstallments": 1,
    "paymentInterval": "MONTHLY",
    "maxDueDateOffset": 30,
    "minDueDateOffset": 1,
    "principalCollected": 100,
    "defaultInstallments": 6,
    "defaultDueDateOffset": 30,
    "currencyRoundingSchedule": "NEAREST",
    "principalRoundingSchedule": "NEAREST"
  },
  "collection": {
    "acceptPrepayment": true,
    "paymentAllocation": "HORIZONTAL",
    "prepaymentAllocationOrder": {
      "fee": 1,
      "penalty": 2,
      "interest": 3,
      "principal": 4
    }
  },
  "penalty": {
    "enablePenalty": false
  },
  "fees": [
    {
      "feeName": "Processing Fee",
      "feeType": "ON_DISBURSEMENT",
      "feePayment": "PERCENTAGE_0F_DISBURSE_AMOUNT",
      "value": 2.5
    },
    {
      "feeName": "Admin Fee",
      "feeType": "ONE_OFF_ON_FIRST_REPAYMENT",
      "feePayment": "FLAT",
      "value": 5000
    },
    {
      "feeName": "Early Liquidation Fee",
      "feeType": "ON_PRE_LIQUIDATION",
      "feePrincipal": "PRINCIPAL",
      "feePayment": "INTEREST",
      "value": 1.5
    }
  ]
}
```

## Update loan product

```
PATCH {base url}/:id 
```

Send only fields to update (same shape as create, all optional).

## List products

```
GET {base url}/list
```

#### Query params

<table><thead><tr><th>Query param</th><th>Description</th><th data-type="checkbox">Optional?</th></tr></thead><tbody><tr><td>search</td><td>Search term</td><td>true</td></tr><tr><td>productType</td><td>Filter by type</td><td>true</td></tr><tr><td>page</td><td>Page number</td><td>true</td></tr><tr><td>limit</td><td>Items per page</td><td>true</td></tr><tr><td>organizationName</td><td>Filter by org name</td><td>true</td></tr><tr><td>startDate</td><td>Filter start date</td><td>true</td></tr><tr><td>endDate</td><td>Filter end date</td><td>true</td></tr></tbody></table>

## Get single product details

```
GET {base url}/:id
```