# 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://oobla.gitbook.io/tyche/reference/loans.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.