# Pezesha (means capital enabler)

CONNECT. ENABLE. EMPOWER

![](/files/-MW9rwoGWrfHMZHkLuJA)

## Statement of Copyright

**© Pezesha Africa Ltd. All rights reserved.**

All product names, company names or trademarks mentioned in this document remain the property of their respective owners. No part of this document may be reproduced in any form without permission from **Pezesha Africa Ltd**.

## **Statement of Confidentiality**

The recipient of this document agrees to keep this document confidential and not to use its contents in any form or by any means without permission from Pezesha Ltd. Moreover, the recipient agrees not to place this document at the disposal of any third party without written permission from Pezesha Africa Ltd.

 If such permission is granted, it will be subject to the condition that the recipient ensures that any third party recipient of this document, or of information contained therein, is held responsible to Pezesha Africa Ltd for the confidentiality of that document or information.

## **API Endpoints & Usage Policy**

The Platform is hosted at the following URLs

* Production - **<https://api.pezesha.com>**
* Develop - **<https://dev.api.pezesha.com>**

{% hint style="warning" %}
All API calls **MUST** be made from a server since the issued credentials are client. (**ONLY server to server communication**)
{% endhint %}


# Get Started

The PEZESHA APIs are customizable & can be tailored to user's request. (Term & Conditions apply)

## Process Flow

The following process flow is used when utilizing these APIs

1. User registration&#x20;
2. Data ingestion
3. Loan offer retrieval&#x20;
4. Loan application
5. Loan status display
6. Loan repayment

{% content-ref url="/pages/-MW9V7EX2tjBX6HDBHAl" %}
[Authentication](/get_started/authentication)
{% endcontent-ref %}

{% content-ref url="/pages/-MW9\_qElwDVCgJKBu2DZ" %}
[Errors & Status Codes](/get_started/errors)
{% endcontent-ref %}


# Authentication

To make API calls on PEZESHA, you’ll have to pass a `Bearer Token`  To generate a token you simply

1. Request credentials from PEZESHA (**Client ID**, **Client Name** & **Client Secret**)
2. Make API call to **`{{BASE_URL}}/oauth/token`** passing in your API Credential. Doesn't have **mfi** prefix
3. You'll be authenticated and receive a token to process further API calls

{% tabs %}
{% tab title="Authentication Format" %}

```yaml
Authorization: Bearer {token}
```

{% endtab %}
{% endtabs %}

## AUTH Token

<mark style="color:green;">`POST`</mark> `{{https://api.pezesha.com or https://dev.api.pezesha.com}}/oauth/token`

Use this endpoint to generate an JWT to be used for authentication in further API calls

#### Headers

| Name         | Type   | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| Content-Type | string | Default (**application/x-www-form-urlencoded**) |

#### Request Body

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| grant\_type    | string | Default (**client\_credentials**) |
| provider       | string | Default (**users**)               |
| client\_secret | string | Provided by Pezesha               |
| client\_id     | string | Provided by Pezesha               |

{% tabs %}
{% tab title="200 You will get this response if everything goes well" %}

```javascript
{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "ACCESS_TOKEN_HERE"
}
```

{% endtab %}

{% tab title="401 If something is wrong" %}

```javascript
{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed"
}
```

{% endtab %}
{% endtabs %}


# Errors & Status Codes

## **Status Codes**

All status codes are standard HTTP status codes. The below ones are used in this API.

* **2XX -** Success of some kind
* **4XX -** Error occurred in client’s part
* **5XX -** Error occurred in server’s part

| **Status Code** | **Description**                                       |
| :-------------: | ----------------------------------------------------- |
|       200       | OK                                                    |
|       201       | Created                                               |
|       202       | Accepted (Request accepted, and queued for execution) |
|       400       | Bad request                                           |
|       401       | Authentication failure                                |
|       403       | Forbidden                                             |
|       404       | Resource not found                                    |
|       405       | Method Not Allowed                                    |
|       409       | Conflict                                              |
|       412       | Precondition Failed                                   |
|       413       | Request Entity Too Large                              |
|       500       | Internal Server Error                                 |
|       501       | Not Implemented                                       |
|       503       | Service Unavailable                                   |


# User Registration

Use this endpoint to register borrowers, merchants or agents onto PEZESHA

{% hint style="warning" %}
**Pezesha ID**

Make sure to persist **customer\_id** as you will need this during loan application (**pezesha\_id**)
{% endhint %}

## Register Merchant

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers`

This endpoint allows you to register merchant on to PEZESHA

#### Headers

| Name                                             | Type   | Description                                                 |
| ------------------------------------------------ | ------ | ----------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Authentication token generated from Authentication Endpoint |

#### Request Body

| Name                | Type      | Description                                                    |
| ------------------- | --------- | -------------------------------------------------------------- |
| terms               | boolean   | User has accepted Pezesha Ts\&Cs                               |
| location            | string    | Location of merchant business                                  |
| merchant\_reg\_date | string    | Date Merchant was first registered in Pezesha partner's system |
| merchant\_id        | string    | Merchant ID in partner's system                                |
| email               | string    | User's email ID                                                |
| dob                 | string    | Date of Birth (**Y-m-d format**)                               |
| phone               | string    | User's phone number                                            |
| full\_names         | string    | Full Names                                                     |
| national\_id        | string    | National ID Number                                             |
| other\_phone\_nos   | string\[] | Other phone numbers tied to merchant                           |
| geo\_location.long  | string    |                                                                |
| geo\_location.lat   | string    |                                                                |
| meta\_data          | array     | Additional data requested by Pezesha in Key Value Pairs        |
| channel             | string    | The Client Name shared by Pezesha                              |

{% tabs %}
{% tab title="200 Registration Successful." %}

```javascript
{
   "error":false,
   "status":200,
   "response_code":0,
   "data":{
      "customer_id":1,
      "customer_names":"John",
      "customer_identification":"292309489",
      "customer_phoneno":"0721234567"
   }
}

```

{% endtab %}

{% tab title="422 Validation error" %}

```javascript
{
  "error": true,
  "status": 422,
  "message": {
	"phone": [
  	"The phone field is required."
	]
  }
}
{
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "geo_location":{
      "long":"",
      "lat":""
   }
}{
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "geo_location":{
      "long":"",
      "lat":""
   }
}{
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "geo_location":{
      "long":"",
      "lat":""
   }
}{
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "geo_location":{
      "long":"",
      "lat":""
   }
}wddwe{
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "geo_location":{
      "long":"",
      "lat":""
   }
}{
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "geo_location":{
      "long":"",
      "lat":""
   }
}
```

{% endtab %}
{% endtabs %}

```json
{
   "channel": "Partner Name",
   "full_names":"John Doe",
   "phone":"254721XXXXXX",
   "other_phone_nos":[
      "25471XXXXXXX",
      "25472XXXXXXXX"
   ],
   "national_id":"12311313",
   "dob":"1999-01-01",
   "email":"example@gmail.com",
   "gender":"Female",
   "merchant_id":"",
   "merchant_reg_date":"",
   "location":"",
   "county":"",
   "sub_county":"",
   "alternative_customer_phoneno":"",
   "next_of_kin_name":"",
   "next_of_kin_phoneno":"",
   "geo_location":{
      "long":"",
      "lat":""
   },
   "meta_data":[
      {
         "key":"",
         "value":""
      }
   ]
}
```


# Terms & Conditions

This API endpoint shows how to inform Pezesha that a merchant has accepted terms & conditions.

{% hint style="info" %}
The indentifier field can be **merchant\_id** *or* **national\_id**
{% endhint %}

## Informs Pezesha that the merchant has accepted the terms & conditions

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers/terms`

#### Headers

| Name          | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| Authorization | String | Bearer token generated from Auth endpoint |

#### Request Body

| Name       | Type    | Description                                   |
| ---------- | ------- | --------------------------------------------- |
| channel    | string  | This is the client name                       |
| identifier | string  | Can be **merchant\_id** *or* **national\_id** |
| terms      | boolean | True for accept & False for Decline Ts\&Cs    |

{% tabs %}
{% tab title="200: OK Request Processed Successfully" %}

```javascript
{
   "error":false,
   "status":200,
   "response_code":0,
   "message": "Request processed successfully"
}

```

{% endtab %}

{% tab title="400: Bad Request Unable to process request" %}

```javascript
{
  "error": true,
  "status": 400,
  "message": "Unable to find merchant"
}
```

{% endtab %}
{% endtabs %}


# Opt Out

Send Opt Out request to Pezesha

## Opt merchant out of Pezesha eco system

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers/opt_out`

Inform Pezesha that a merchant has opted out from Pezesha

#### Headers

| Name          | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| Authorization | string | Token generated from Auth endpoint |

#### Request Body

| Name       | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| channel    | string | Client name                                 |
| identifier | stri   | Can be **merchant\_id** or **national\_id** |


# Data Ingestion

Upload merchant's historical transactional information into Pezesha Credit Scoring Model.

## Upload Transactions

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1.1/data`

This endpoint allows you to upload historical transactional record for a user/merchant so that they can get a **credit score**. A credit score is used to determine the user's loan limits.\
\
The **MAX** number of transactions allowed in the transactions array is **200 records**.  It is important that at least **6 months** worth of data be uploaded when a user is registered so that they can be able to get a loan offer. This can be done in a **background job** once a user has been registered.\
\
The **other\_details** section will be used to upload any additional information requested by the credit scoring team.

#### Headers

| Name                                             | Type   | Description                                                    |
| ------------------------------------------------ | ------ | -------------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Authentication token to track down who is emptying our stocks. |

#### Request Body

| Name                                           | Type   | Description                                                            |
| ---------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| transactions.other\_details                    | array  | Key Value pair for additional fields requested by Credit Scoring Team  |
| transactions.transaction\_time                 | string | Time of transaction                                                    |
| transactions.face\_amount                      | number | Amount                                                                 |
| transactions.merchant\_id                      | string | Merchant ID                                                            |
| transactions.transaction\_id                   | string | Transaction ID                                                         |
| transactions<mark style="color:red;">\*</mark> | array  | An array containing multiple transaction records                       |
| channel<mark style="color:red;">\*</mark>      | string | Client Name provided by Pezesha during account setup (**Capitalized**) |

{% tabs %}
{% tab title="200  Data has been uploaded successfully" %}

```javascript
{
   "status": 200,
   "response_code": 0,
   "error": false,
   "message": "Request processed successfully"
}

```

{% endtab %}

{% tab title="400 Could not process request." %}

```
{
   "status": 400,
   "response_code": 0,
   "error": true,
   "message": "Unable to process request"
}

```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request Payload" %}

```javascript
{
   "channel": "Partner Name",
   "transactions":[
      {
         "transaction_id": "TR12356",
         "merchant_id": "MC12356",
         "face_amount": 400,
         "transaction_time": "2021-01-03 19:12:34",
         "other_details": [
            {
               "key": "location",
               "value": "Nairobi"
            },
            {
               "key": "category",
               "value": "OILS"
            }
         ]
      }
   ]
}

```

{% endtab %}
{% endtabs %}


# Loan Offers

Get a user's loan limit

Use this endpoint to get a user's loan limit based on their credit score.

## Loan Offers

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers/options`

Get user's loan limit

#### Headers

| Name                                            | Type   | Description                  |
| ----------------------------------------------- | ------ | ---------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Generated from Auth endpoint |

#### Request Body

| Name                                         | Type   | Description                     |
| -------------------------------------------- | ------ | ------------------------------- |
| channel<mark style="color:red;">\*</mark>    | string | Client Name provided by Pezesha |
| identifier<mark style="color:red;">\*</mark> | string | Merchant ID                     |

{% tabs %}
{% tab title="200 Successful response" %}

```javascript
{
    "status": 200,
    "response_code": 0,
    "error": false,
    "message": "Merchant Decision Options",
    "data": {
        "amount": 10000,
        "rate": "0.50",
        "fee": 100,
        "duration": 7,
        "interest": 50
    }
}
```

{% endtab %}

{% tab title="202 HTTP 200: OK" %}

```javascript
{
  "error": true,
  "status": 200,
  "response_code": 0,
  "message": "Unable to get loan offers at this point"
}

```

{% endtab %}
{% endtabs %}

```javascript
{
    "identifier": "1154980",
    "channel": "Partner Name"
}
```


# Loan Application

Apply for loan on behalf of merchant/customer

## Loan Application

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers/loans`

This endpoint allows you to apply for a loan on behalf of your user.&#x20;

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

#### Request Body

| Name                           | Type   | Description                             |
| ------------------------------ | ------ | --------------------------------------- |
| pezesha\_id                    | string | Pezesha ID returned during registration |
| channel                        | string | Client Name given by Pezesha            |
| amount                         | string | Loan Amount entered by user             |
| duration                       | string | Loan duration from Offers endpoint      |
| interest                       | string | Loan Interest Amount                    |
| rate                           | string | Loan Interest Rate                      |
| fee                            | string | Service Fee from Offers endpoint        |
| payment\_details.type          | string |                                         |
| payment\_details.number        | string |                                         |
| payment\_details.callback\_url | string |                                         |

{% tabs %}
{% tab title="200 Loan application successful." %}

```javascript
{
   "status":200,
   "response_code":0,
   "error":false,
   "message":"Loan approved",
   "data":{
      "loan_id":94202
   }
}
```

{% endtab %}

{% tab title="400 Could not make loan application." %}

```javascript
{
   "status":200,
   "response_code":0,
   "error":false,
   "message":"Your last loan was paid late. You don't qualify for a loan"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
For Partners managing a **Pezesha wallet**, make sure to persist the **Loan ID** as it is needed during Loan Repayment.
{% endhint %}

{% tabs %}
{% tab title="Request Payload" %}

```javascript
{
 "pezesha_id": 239831,
 "amount": 500,
 "duration": 30,
 "interest": 50,
 "rate": 10,
 "fee": 10,
 "channel": "Partner Name",
 "payment_details": {
   "type": "BUY_GOODS/PAYBILL",
   "number": "898927",
   "callback_url": "https://example.com/callback"
 }
}
```

{% endtab %}
{% endtabs %}


# Loan Status

Get loan information for a user's latest loan

This endpoint is used to get a borrower’s latest loan status on the Pezesha platform. A loan can be in the following statuses:

* **Processing** - Loan is being prepared for disbursement
* **Score** - Merchant/Customer is being scored to confirm they are still eligible for a limit.
* **Funding** - Loan is being sent to the payment provider for disbursement.
* **Funded** - The loan has been disbursed and its duration is on course.
* **Paid -** Loan has been paid for.
* **Cancelled** - Loan has been cancelled.
* **Late** - The user is late on payment against the loan.

## Loan Status

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers/latest`

Get latest loan status

#### Headers

| Name                                            | Type   | Description              |
| ----------------------------------------------- | ------ | ------------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | Token from Auth endpoint |

#### Request Body

| Name                                         | Type   | Description                  |
| -------------------------------------------- | ------ | ---------------------------- |
| channel<mark style="color:red;">\*</mark>    | string | Client Name given by Pezesha |
| identifier<mark style="color:red;">\*</mark> | string | Merchant ID                  |

{% tabs %}
{% tab title="200 Latest loan status" %}

```javascript
{
   "error":false,
   "status":200,
   "message":"Success!",
   "response_code":0,
   "data":{
      "loan_id":50553,
      "customer_id":5043,
      "channel":"CHANNEL",
      "loan_amount":5000,
      "interest":500,
      "status":"Processing",
      "application_date":"2018-07-20 11:21:58",
      "funded_time":"2018-07-20 11:21:58"
   }
}
```

{% endtab %}
{% endtabs %}


# Loan History

Get a merchant's loan history

## Get Loan History

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/borrowers/statement`

Get a merchant's loan history

#### Headers

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer token from AUTH endpoint |

#### Request Body

| Name                                             | Type   | Description         |
| ------------------------------------------------ | ------ | ------------------- |
| identification<mark style="color:red;">\*</mark> | String | Borrower identifier |
| page                                             | int    | Page of statements  |

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

```javascript
{
    "status": 200,
    "response_code": 0,
    "error": false,
    "message": "Loans Records Found",
    "data": [
        {
            "loan_id": 102872,
            "loan_amount": "10.00",
            "app_interest_value": "2.00",
            "app_service_value": "0.00",
            "app_penalty_value": "0.00",
            "loan_status": "Paid",
            "mpesa_time": "2021-10-26 14:43:56",
            "loan_date": "2021-10-26",
            "loan_duedate": "2021-11-25",
            "amount_due": 0,
            "overduedays": 0,
            "penalty": 0,
            "amount_principal": "10.00",
            "amount_expected": 12,
            "amount_repaid": 12,
            "amount_balance": 0,
            "penalty_expected": 0,
            "penalty_repaid": 0,
            "penalty_balance": 0,
            "net_balance": 0
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found Unable to find loan history" %}

```javascript
{
    "status": 404,
    "response_code": 0,
    "error": true,
    "message": "No Loans Records Found"
}
```

{% endtab %}
{% endtabs %}


# Active Loans

As a partner use this endpoint to get all your customers active loans (Loans not fully repaid) on Pezesha.

## Get Active Loans

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/mfi/v1/borrowers/active/:merchant_key`

This endpoint allows a partner with Pezesha to get all their clients active loans&#x20;

#### Query Parameters

| Name                                            | Type   | Description                      |
| ----------------------------------------------- | ------ | -------------------------------- |
| merchant\_key<mark style="color:red;">\*</mark> | string | Merchant key provided by pezesha |

#### Headers

| Name                                             | Type   | Description                                                 |
| ------------------------------------------------ | ------ | ----------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Authentication token generated from Authentication Endpoint |

{% tabs %}
{% tab title="200 Active loans successfully retrieved." %}

```
{
    "status": 200,
    "response_code": 0,
    "error": false,
    "message": "Active Loans!",
    "data": [
        {
            "loan_id": 10101,
            "channel": "PARTNERCHANNEL",
            "customer_names": "Jane Doe",
            "merchant_id": "merchant_jane",
            "loan_amount": "3000.00",
            "loan_appdate": "2020-01-20 12:33:04",
            "loan_status": "Funded"
        },
        {
            "loan_id": 10102,
            "channel": "PARTNERCHANNEL",
            "customer_names": "John Doe",
            "merchant_id": "merchant_john",
            "loan_amount": "2000.00",
            "loan_appdate": "2020-01-20 12:33:04",
            "loan_status": "Funded"
        }
        ]
}
```

{% endtab %}

{% tab title="404 No Partner active loans found" %}

```
{
    "status": 404,
    "response_code": 0,
    "error": true,
    "message": "No active loans found!"
}
```

{% endtab %}
{% endtabs %}


# Loan Repayment Schedule

use this endpoint to repayment schedule for a borrowers loan.

The repayment schedule can be Daily, Weekly or Monthly depending on the partners agreement with Pezesha. A repayment schedule can have the following statuses

* **Active on Schedule** - the schedule is active and payment is on schedule
* **Paid** - the schedule has already been paid
* **Overdue** - the schedule is overdue i.e payment is late

{% hint style="info" %}
in the loan schedule response, 'month' is used as a placeholder i.e it can represent day, week or month depending on the the partners loan schedule agreement with pezesha
{% endhint %}

## Get Cakes

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/mfi/v1/borrowers/repayment-shedules`

Get user loan repayment schedule

#### Query Parameters

| Name                                           | Type   | Description                                             |
| ---------------------------------------------- | ------ | ------------------------------------------------------- |
| channel<mark style="color:red;">\*</mark>      | string | Client Name given by Pezesha                            |
| merchant\_id<mark style="color:red;">\*</mark> | string | Merchant id for whom to see the loan repayment schedule |

#### Headers

| Name                                             | Type   | Description                                                 |
| ------------------------------------------------ | ------ | ----------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Authentication token generated from Authentication endpoint |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "response_code": 0,
    "error": false,
    "message": "Loans Repayment Schedule",
    "data": [
        {
            "loan_id": 10101,
            "repayment_date": "2020-07-03",
            "month": 1,
            "principal_amount": 500,
            "interest_amount": 0,
            "penalty_amount": 0,
            "penalty_paid": 0,
            "total_due": 500,
            "total_outstanding": 1000,
            "balance": 500,
            "status": "Active on Schedule"
        },
        {
            "loan_id": 10101,
            "repayment_date": "2020-07-03",
            "month": 2,
            "principal_amount": 500,
            "interest_amount": 0,
            "penalty_amount": 0,
            "penalty_paid": 0,
            "total_due": 500,
            "total_outstanding": 500,
            "balance": 500,
            "status": "Active on Schedule"
        },
        {
            "loan_id": 10101,
            "repayment_date": "2020-07-04",
            "month": 3,
            "principal_amount": 500,
            "interest_amount": 0,
            "penalty_amount": 0,
            "penalty_paid": 0,
            "total_due": 500,
            "total_outstanding": 0,
            "balance": 500,
            "status": "Active on Schedule"
        }
        
    ]
}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{
    "status": 404,
    "response_code": 0,
    "error": true,
    "message": "Unable to find active loan tied to merchant"
}
```

{% endtab %}
{% endtabs %}


# Pezesha Wallet

APIs to manage Pezesha's Wallets

For certain partnerships, Pezesha allows **Trusted Partners** to manage a wallet within their own Infrastructure. These partners will seek for **Authorization** from Pezesha so to use the funds within the wallet to fund loans.&#x20;

{% hint style="danger" %}
The APIs in this section apply **ONLY** for partners who manage a Pezesha wallet within their System.
{% endhint %}


# Loan Confirmation

Confirm that loan has been funded

## Loan Confirmation

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/loans/confirmation`

This endpoint allows you to get free cakes.

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

#### Request Body

| Name                  | Type    | Description                                  |
| --------------------- | ------- | -------------------------------------------- |
| success               | boolean | Whether the loan has been funded or not      |
| message               | string  | Description of loan status                   |
| loan\_id              | string  | Loan ID gotten from loan application         |
| channel               | string  | Client Name gotten from Pezesha              |
| data                  | object  | Transaction data                             |
| data.trans\_reference | string  | Reference for transaction                    |
| data.trans\_time      | string  | Transaction Time                             |
| data.trans\_amount    | number  | Transaction Amount                           |
| data.wallet\_balance  | number  | New Pezesha Wallet Balance after transaction |

{% tabs %}
{% tab title="200 Loan confirmed successfully" %}

```json
{
   "status":200,
   "response_code":0,
   "error":false,
   "message":"Payment processed successfully"
}
```

{% endtab %}

{% tab title="404 Error confirming loan" %}

```json
{
   "status":400,
   "response_code":0,
   "error":false,
   "message":"Unable to process request"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Loan ID**&#x20;

This is gotten from Loan Application response
{% endhint %}

{% hint style="info" %}
**Loan Confirmation**

You can let Pezesha know whether a loan has been disbursed successfully or not using this callback
{% endhint %}

{% tabs %}
{% tab title="Loan Funded Successfully" %}

```javascript
{
   "status":200,
   "response_code":0,
   "error":false,
   "message":"Payment processed successfully"
}
```

{% endtab %}

{% tab title="Failed To Fund Loan" %}

```javascript
{
   "status":400,
   "response_code":0,
   "error":false,
   "message":"Unable to process request"
}
```

{% endtab %}
{% endtabs %}


# Loan Repayment

Send loan repayment confirmation

## Send Loan Repayment Confirmation

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v1/loans/repayment`

Post a loan confirmation request to Pezesha

#### Headers

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer token from AUTH endpoint |

#### Request Body

| Name                                               | Type   | Description                     |
| -------------------------------------------------- | ------ | ------------------------------- |
| merchant\_id<mark style="color:red;">\*</mark>     | String | Borrower identifier             |
| channel<mark style="color:red;">\*</mark>          | String | Partner name                    |
| trans\_amount<mark style="color:red;">\*</mark>    | String | Transaction amount in String    |
| trans\_time<mark style="color:red;">\*</mark>      | String | Transaction datetime in String  |
| trans\_reference<mark style="color:red;">\*</mark> | String | Transaction reference in String |
| wallet\_balance<mark style="color:red;">\*</mark>  | String | The wallet balance              |

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

```javascript
{
    "status": 200,
    "response_code": 0,
    "error": false,
    "message": "Repayment successful",
}
```

{% endtab %}

{% tab title="400: Bad Request Unable to process request" %}

```javascript
{
    "status": 400,
    "response_code": 0,
    "error": true,
    "message": "Unable to process request"
}
```

{% endtab %}
{% endtabs %}


# Pezesha Mpesa STK

This endpoint enables easier payment experience for Pezesha Partners

## Initiate STK Push

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/mfi/v2/mpesa/stk`

Request merchant for funds using Mpesa's STK push to Pezesha's Paybill

#### Headers

| Name          | Type   | Description              |
| ------------- | ------ | ------------------------ |
| Authorization | String | Token from AUTH endpoint |

#### Request Body

| Name                                      | Type   | Description                               |
| ----------------------------------------- | ------ | ----------------------------------------- |
| amount<mark style="color:red;">\*</mark>  | String | Amount merchant wants to pay              |
| phone<mark style="color:red;">\*</mark>   | String | Phone number to make payment (+254)       |
| account<mark style="color:red;">\*</mark> | String | Account merchant wants to direct funds to |

{% tabs %}
{% tab title="200: OK STK requested successfully" %}

```javascript
{
    "status": 200,
    "response_code": 0,
    "error": false,
    "message": "STK Request Submitted Successfully"
}
```

{% endtab %}

{% tab title="400: Bad Request Validation Error" %}

```javascript
{
    "status": 422,
    "message": "Validation Error",
    "errors": {
        "amount": [
            "The amount field is required."
        ],
        "phone": [
            "The phone field is required."
        ],
        "account": [
            "The account field is required."
        ]
    }
}
```

{% endtab %}
{% endtabs %}


# FAQs

## Where do I get API credential?

Send an email to **<hello@pezesha.com>** requesting for your API credentials