> For the complete documentation index, see [llms.txt](https://oobla.gitbook.io/tyche/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oobla.gitbook.io/tyche/reference/loans.md).

# Loans

#### Add loan

## Create a new loan

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans`

#### Headers

| Name                                                   | Type   | Description         |
| ------------------------------------------------------ | ------ | ------------------- |
| Authorization header<mark style="color:red;">\*</mark> | string | API user secret key |

#### Request Body

| Name                                                | Type   | Description              |
| --------------------------------------------------- | ------ | ------------------------ |
| loanProductId<mark style="color:red;">\*</mark>     | String | loan product id          |
| name<mark style="color:red;">\*</mark>              | String | loan name                |
| amount<mark style="color:red;">\*</mark>            | Number | loan amount(major)       |
| interestRate                                        | Number | loan interest rate       |
| moratorium                                          | Number | loan moratorium          |
| tenure                                              | Number | loan tenure              |
| accountHolder<mark style="color:red;">\*</mark>     | String | id of the client/company |
| accountHolderType<mark style="color:red;">\*</mark> | String | clients/companies        |
| loanApplicationDate                                 | string | application date         |

{% tabs %}
{% tab title="201: Created Loan created successfully" %}

```json
{
    "responseCode": "00",
    "status": "success",
    "message": "loan created successfully",
    "data": {
        "organizationId": "aee1a803-3835-4195-b732-a19f7c3702c8",
        "accountHolderType": "clients",
        "loanName": "third loan with repayment schedule",
        "amount": 10000,
        "accountNumber": "16050926853",
        "accountHolder": "d4c9f36f-ffbb-4c85-87cb-97c8fee6b9ad",
        "interestRate": 12,
        "moratorium": 6,
        "tenure": 90,
        "tranches": null,
        "state": "PENDING",
        "customData": {},
        "document": null,
        "depositAccount": null,
        "loanProductId": "798ca840-07c7-4226-ba10-52b722d8d968",
        "balances": {
            "totalAccruedFees": 0,
            "totalAccruedPenalty": 0,
            "totalAccruedinterest": 0,
            "totalPrincipalBalance": 10000
        },
        "gracePeriod": null,
        "riskState": null,
        "comment": null,
        "writtenOffDate": null,
        "approvedDate": null,
        "disbursedDate": null,
        "declinedDate": null,
        "nextRepaymentDate": null,
        "lastRepaymentDate": null,
        "id": "bd63129a-41d5-417c-a48a-c8377a901390",
        "totalDue": 0,
        "totalPaid": 0,
        "status": "inactive",
        "created_at": "2024-03-12T13:51:00.529Z",
        "updated_at": "2024-03-12T13:51:00.529Z"
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised" %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

## Update loan

<mark style="color:purple;">`PATCH`</mark> `{base url}/v1/loans`

Update a single loan

#### Headers

| Name                                                   | Type   | Description         |
| ------------------------------------------------------ | ------ | ------------------- |
| Authorization header<mark style="color:red;">\*</mark> | string | API user secret key |

#### Path Param

| Name                                     | Type   | Description                  |
| ---------------------------------------- | ------ | ---------------------------- |
| loanId<mark style="color:red;">\*</mark> | String | id of the loan to be updated |

**Request Body**<br>

| Name                                    | Type   | Description                                        |
| --------------------------------------- | ------ | -------------------------------------------------- |
| state<mark style="color:red;">\*</mark> | string | <p>Possible values are:<br>APPROVED, DECLINED.</p> |
| comment                                 | text   |                                                    |
|                                         |        |                                                    |

{% tabs %}
{% tab title="201: " %}

```json
{"message":"Loan updated successfully"}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised" %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Get all loan accounts

## Get all loan accounts

<mark style="color:blue;">`GET`</mark> `{base url}/v1/loans`

Get all loan accounts

{% tabs %}
{% tab title="200: OK Loan accounts fetched successsfully" %}

```json
{
    "responseCode": "00",
    "status": "success",
    "message": "Loans fetch successful",
    "data": [
        {
            "id": "bb630816-db35-4fe8-acdd-773a0387cdbd",
            "organizationId": "a5f38f16-6c44-408f-b7ff-6775f02b83ac",
            "loanName": "testing",
            "loanProductId": "fed36374-fcd2-4fac-a820-8100a6ae97af",
            "amount": 3000,
            "totalDue": 0,
            "totalPaid": 0,
            "accountNumber": "0000000427",
            "accountHolderType": "companies",
            "accountHolder": "05768940-15ed-450c-8d8e-70f36ffffff8",
            "tenure": 20,
            "customData": {},
            "document": null,
            "tranches": null,
            "status": "inactive",
            "state": "PENDING",
            "riskState": "PERFOMRING",
            "created_at": "2023-08-23T14:55:11.358Z",
            "updated_at": "2023-08-23T14:55:11.358Z",
            "firstName": null,
            "lastName": null,
            "clientkey": null,
            "name": "chowDeck",
            "accountholdername": "chowDeck",
            "companykey": "05768940-15ed-450c-8d8e-70f36ffffff8",
            "loanproductname": "test45",
            "currency": "NGN"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised" %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Get loan account details

## Get loan account details

<mark style="color:blue;">`GET`</mark> `{base url}/v1/loans`

Get loan account details

#### Path Parameters

| Name                                     | Type   | Description     |
| ---------------------------------------- | ------ | --------------- |
| loanId<mark style="color:red;">\*</mark> | string | id of the loan. |

{% tabs %}
{% tab title="200: OK Loan fetch successful" %}

```json
{
    "responseCode": "00",
    "message": "Loan fetch successful",
    "data": {
        "id": "e7837f5f-5793-4b0f-bfc7-5f1e4926ace3",
        "organizationId": "ab3b150e-6a5d-429f-b499-f2d6ea99f668",
        "loanName": "No fees loan",
        "loanProductId": "29afa5b5-4d1b-4971-b407-bf421513a669",
        "amount": 100000,
        "totalDue": 0,
        "totalPaid": 0,
        "interestRate": 0,
        "gracePeriod": null,
        "accountNumber": "0000002825",
        "accountHolder": "a3ffa926-14ae-4a82-a9b7-9b27c7df7867",
        "accountHolderType": "clients",
        "tenure": 2,
        "customData": {
            "3rd": "33",
            "fffff": "ttgggg3",
            "4th boolean": "3333",
            "loan custom": "https://res.cloudinary.com/dtui4qk9s/image/upload/v1701709300/uploads/idmcp0elm7hi74jjubik.png"
        },
        "balances": {
            "totalAccruedFees": 0,
            "totalAccruedPenalty": 0,
            "totalAccruedinterest": 0,
            "totalPrincipalBalance": 0
        },
        "tranches": null,
        "status": "inactive",
        "document": null,
        "state": "WRITTENOFF",
        "riskState": "PERFOMRING",
        "comment": null,
        "created_at": "2023-12-04T17:01:43.122Z",
        "updated_at": "2023-12-07T16:55:10.568Z",
        "firstName": "no ref",
        "lastName": "client",
        "clientkey": "a3ffa926-14ae-4a82-a9b7-9b27c7df7867",
        "name": null,
        "accountholdername": null,
        "companykey": null,
        "loanproductname": "No fees loan",
        "currency": "NGN"
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Get loan schedule

## Get loan schedule

<mark style="color:blue;">`GET`</mark> `{base url}/v1/loans/{loanId}/repayments`

**`Request Param`**

| Name   | Type | Description     |
| ------ | ---- | --------------- |
| loanId | uuid | id of the loan. |

{% tabs %}
{% tab title="200: OK Loan schedule fetch successfully" %}

```json
{
    "responseCode": "00",
    "message": "Loan fetch successfully",
    "data": [
        {
            "id": "3df52413-295e-4de6-8230-6d9853265aef",
            "loanId": "e7837f5f-5793-4b0f-bfc7-5f1e4926ace3",
            "principal": 0,
            "interest": 0,
            "fee": 0,
            "penalty": 0,
            "totalDue": 0,
            "totalPaid": 0,
            "state": "WRITTENOFF",
            "dueDate": "2023-12-20",
            "created_at": "2023-12-04T17:01:43.122Z",
            "updated_at": "2023-12-07T16:55:10.228Z"
        },
        {
            "id": "39fa7101-a79d-4521-b285-bef2849309d7",
            "loanId": "e7837f5f-5793-4b0f-bfc7-5f1e4926ace3",
            "principal": 0,
            "interest": 0,
            "fee": 0,
            "penalty": 0,
            "totalDue": 0,
            "totalPaid": 0,
            "state": "WRITTENOFF",
            "dueDate": "2024-01-03",
            "created_at": "2023-12-04T17:01:43.122Z",
            "updated_at": "2023-12-07T16:55:10.228Z"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Get loan transactions

## Get loan transactions

<mark style="color:blue;">`GET`</mark> `{base url}/v1/loans/transactions`

Get loan transactions

#### Query Parameters

| Name                                            | Type   | Description                            |
| ----------------------------------------------- | ------ | -------------------------------------- |
| accountNumber<mark style="color:red;">\*</mark> | string | account number generated for the loan. |

{% tabs %}
{% tab title="200: OK Transactions fetched successfully" %}

```json
{
    "status": "success",
    "message": "Transactions fetched successfully",
    "data": [],
    "pagination": {
        "currentPage": 1,
        "perPage": 15,
        "totalCount": 0,
        "totalPages": 0,
        "previousPage": 0,
        "nextPage": 0
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Get loan balances

## Get loan balances

<mark style="color:blue;">`GET`</mark> `{base url}/v1/loans/{loanId}/balances`

Get loan balances

**Request Param**<br>

| Name   | Type | Descriopiton   |
| ------ | ---- | -------------- |
| loanId | uuid | id of the loan |

{% tabs %}
{% tab title="200: OK Loan balances fetch successfully" %}

```json
{
    "responseCode": "00",
    "message": "Loan balances fetch successfully",
    "data": {
        "balances": {}
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Repay loan

## Repay loan

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans/transaction/{loanId}/repay`

Repay loan

**Request Param**

| Name   | Type | Description    |
| ------ | ---- | -------------- |
| loanId | uuid | id of the loan |

#### Request Body

| Name                                     | Type   | Description                                               |
| ---------------------------------------- | ------ | --------------------------------------------------------- |
| channel                                  | string | id of the channel attached when disbursing internal loan. |
| amount<mark style="color:red;">\*</mark> | number | amount(major)                                             |

{% tabs %}
{% tab title="200: OK Loan repayment succesfull" %}

```
{
    "responseCode": "00",
    "message": "loan repayment successful"
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Loan payoff

## Loan payoff

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans/transaction/{loanId}/payoff`

Loan payoff

**Request Param**

| Name   | Type | Description    |
| ------ | ---- | -------------- |
| loanId | uuid | id of the loan |

#### Request Body

| Name                                     | Type   | Description   |
| ---------------------------------------- | ------ | ------------- |
| channel                                  | string | channel       |
| amount<mark style="color:red;">\*</mark> | number | amount(major) |

{% tabs %}
{% tab title="200: OK loan payoff successful" %}

```
{
    "responseCode": "00",
    "message": "loan payoff successful"
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

## Loan WriteOff

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans/transaction/{loanId}/payoff`

Loan write-off

#### Request Body

| Name                                     | Type   | Description    |
| ---------------------------------------- | ------ | -------------- |
| amount<mark style="color:red;">\*</mark> | number | amount (major) |

{% tabs %}
{% tab title="200: OK loan write-off successful" %}

```
{
    "responseCode": "00",
    "message": "loan writeoff successful"
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### loan topup

## Loan topup

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans/transaction/{loanId}/topup`

Loan topup

#### Request Body

<table><thead><tr><th width="236">Name</th><th width="131">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code> <mark style="color:red;">*</mark></td><td>number</td><td>loan amount (major)</td></tr><tr><td><code>interest</code> </td><td>number</td><td>interest</td></tr><tr><td><code>tenure</code></td><td>number</td><td>tenure</td></tr><tr><td><code>firstRepaymentDate</code></td><td>string</td><td>first repayment date</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Loan topup succesfull" %}

```json
{
    "responseCode": "00",
    "message": "Loan topup succesfull"
}
```

{% endtab %}

{% tab title="400: unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### Liquidate loan

## Liquidate loan

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans/transaction/{loanId}/liquidate`

Liquidate loan

#### Request Body

| Name                                        | Type   | Description         |
| ------------------------------------------- | ------ | ------------------- |
| `amount` <mark style="color:red;">\*</mark> | number | loan amount (major) |
| `channel`                                   | string | channel             |

{% tabs %}
{% tab title="200: Ok loan liquidate succesfull" %}

```
{
    "responseCode": "00",
    "message": "loan liquidate succesfull"
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}

#### disburse loan

## Disburse loan

<mark style="color:green;">`POST`</mark> `{base url}/v1/loans/transaction/{loanId}/disburse`

disburse loan

**Headers**

| Name                                                         | Value            |
| ------------------------------------------------------------ | ---------------- |
| `Authorization header`` `<mark style="color:red;">`*`</mark> | `API secret key` |

**Request Param**

| Name   | Type | Decsription    |
| ------ | ---- | -------------- |
| loanId | uuid | id of the loan |

**Body**

<table><thead><tr><th width="299">Name</th><th width="129">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code> <mark style="color:red;">*</mark> </td><td>string</td><td>type (INTERNAL/EXTERNAL)</td></tr><tr><td>accountNumber</td><td>string</td><td>nuban account number is required if type is INTERNAL</td></tr><tr><td><code>narration</code></td><td>string</td><td>narration</td></tr><tr><td><code>channel</code> </td><td>string</td><td>channel is required if type is INTERNAL</td></tr><tr><td><code>changeFirstRepaymentDate</code> <mark style="color:red;">*</mark></td><td>boolean</td><td>change repayment date</td></tr><tr><td><code>firstRepaymentDate</code> </td><td>string</td><td>new first repayment date. required if <code>changeFirstRepaymentDate is set to true.</code></td></tr><tr><td><code>disburseDate</code></td><td>string</td><td>loan disburse date</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200: OK Loan disbursed succesfully" %}

```json
{
    "responseCode": "00",
    "message": "Loan disbursed succesfully"
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorised " %}

```json
{
    "message": "No authorization token found",
    "code": 90
}
```

{% endtab %}
{% endtabs %}