Loan

Initiate loan application

POST {{baseUrl}}/api/v2/client/loans/onboardcustomer_loanrequest

Endpoint to process borrower onboarding and loan application.

Request Body

Name	Type	Description
last_name	string	The last name of the borrower.
first_name	number	The first name of the borrower.
bank_account_name*	string	The name of the borrower's bank account. This is required only for non Nigerian aggregators.
identity_number	string	This is the unique valid identification number of the borrower used to perform KYC.
photo_url	string	The base 64 image of the borrower or the url of the uploaded image.
gender	string	The gender of the borrower should either be male or female.
phone_number*	string	The borrower's phone number.
email*	string	The borrower's email.
company_name	string	The name of the company being registered for corporate borrower.
borrower_type*	number	The type of borrower to be onboarded. 1 for individual and 2 for corporate.
date_of_birth	string	Borrower's date of birth in the format yyyy-MM-dd
state*	string	State of the borrower. To view list of states under an aggregator see Get Country's States endpoint above.
city*	string	City of the borrower.
residence_address	string	Address of the borrower.
company_city	string	City where the company is located for the corporate borrower.
company_address	string	Company address for corporate borrower.
registration_number	string	Company's business registration number for the corporate borrower.
country_code*	string	Certified country code is entered here such as "NG" (Nigeria), "GH" (Ghana), "SA" (South Africa)
sector_code*	string	The sector code of the borrower applying for the loan. To view all sectors and their sector codes, see the Get Sectors endpoint above.
product_id*	number	The Id of the product from which the loan is being requested. To view, all the products for a particular aggregator see the Get Aggregator Product endpoint above.
aggregator_loan_ref*	string	The unique loan reference for the aggregator. This will be generated by the client.
bank_code*	string	The bank code of the borrower's bank. To view, all banks and their bank codes see the Get Country's Bank List endpoint above.
bank_account_num*	string	The bank account number of the borrower.
company_state	string	State where the company is located for the corporate borrower. To view all states for an aggregator nationality, see Get Country's State endpoint above.
create_wallet	boolean	This indicates if a wallet is to be created for a borrower or not (true or false).
customer_category	string	The customer's job category.
loan_purpose*	string	The reason for which the loan is created.
annual_interest_rate*	string	The loan interest rate. If the interest rate is zero, the loan product's interest rate will be used.
loan_amount*	number	The amount to be loaned out.
loan_tenure*	number	The duration of the loan is in months.

---

Get borrower loans

GET {{baseUrl}}/api/v2/client/loans/borrower/{customer_id}

This endpoint is to get all the loans for a specific customer.

Path Parameters

Name	Type	Description
customer_id*	number	The id of the customer

Headers

Name	Type	Description
client-id*	string	The client id that was generated
api-key*	string	The secret api key.

---

Get loan details

GET {{baseUrl}}/api/v2/client/loans/{loan_ref_no}

This endpoint is to get the loan details of a specific loan using the loan reference number.

Path Parameters

Name	Type	Description
loan_ref_no*	string	The loan reference number

Headers

Name	Type	Description
client-id*	string	The client id that was generated
api-key*	string	The secret api key.

200: OK

{
    "message": "Success",
    "status": true,
    "status_code": 200,
    "data": {
        "customer": {
            "id": 1016,
            "first_name": "Feranmi",
            "last_name": "Adedeji",
            "phone_number": "090142*****",
            "bank_name": "Access Bank",
            "bank_id": 1,
            "bank_account_number": "18021******",
            "bank_account_name": "AYODEJI MICHAEL ADEDEJI"
        },
        "repayment_account": {
            "customer_id": 1016,
            "bank_name": "VFD MFB",
            "bank_code": "999999",
            "currency": "NGN",
            "account_number": "1001****2",
            "account_name": "Advancly -Eddie Franecki"
        },
        "loan_details": {
            "loan_id": 3153,
            "decline_reason": null,
            "loan_interest_amount": 28068.17,
            "loan_interest_rate": 54.00,
            "loan_outstanding": 80768.170000,
            "loan_due_date": "2025-01-30T00:00:00",
            "loan_status": "active",
            "loan_status_code": 300,
            "total_loan_collected": 0,
            "total_loan_repaid": 0,
            "is_active": true,
            "loan_tenure": 360,
            "loan_amount": 52700.00,
            "currency": "NGN",
            "loan_amount_repay": 0.000000,
            "settlement_day": "2024-02-06T00:00:00",
            "has_disburse": true,
            "loan_repayment_balance": 0.00,
            "loan_ref": "3246E0641A",
            "aggregator_loan_ref": null,
            "parent_rollover_loan_reference": null,
            "rollover_loan_reference": null,
            "is_rollover": false,
            "can_rollover": false,
            "has_repaid": false,
            "loan_transfer_status": "success",
            "loan_effective_date": "2024-02-05T00:00:00",
            "pub_date": "2024-02-05T16:03:21.879364",
            "modified_date": "2024-02-05T16:03:21.879365",
            "repayment_type": "monthly",
            "status": "Active"
        },
        "repayments": [],
        "repayment_schedule": {
            "currency": {
                "code": "NGN",
                "name": "Nigerian Naira",
                "decimalPlaces": 2,
                "inMultiplesOf": 1,
                "displaySymbol": null,
                "nameCode": "currency.NGN",
                "displayLabel": "Nigerian Naira [NGN]"
            },
            "loanTermInDays": 360,
            "totalPrincipalDisbursed": 52700.00,
            "totalPrincipalExpected": 52700.00,
            "totalPrincipalPaid": 0.00,
            "totalInterestCharged": 28068.17,
            "totalFeeChargesCharged": 0.00,
            "totalPenaltyChargesCharged": 0.00,
            "totalWaived": 0.00,
            "totalWrittenOff": 0.00,
            "totalRepaymentExpected": 80768.17,
            "totalRepayment": 0.00,
            "totalPaidInAdvance": 0.00,
            "totalPaidLate": 0.00,
            "totalOutstanding": 80768.17,
            "periods": [
                {
                    "dueDate": [
                        2024,
                        2,
                        5
                    ],
                    "principalDisbursed": 52700.000000,
                    "principalLoanBalanceOutstanding": 52700.000000,
                    "feeChargesDue": 0.000000,
                    "feeChargesPaid": 0.000000,
                    "totalOriginalDueForPeriod": 0.000000,
                    "totalDueForPeriod": 0.000000,
                    "totalPaidForPeriod": 0.000000,
                    "totalActualCostOfLoanForPeriod": 0.000000,
                    "period": 0,
                    "fromDate": null,
                    "obligationsMetOnDate": null,
                    "complete": false,
                    "daysInPeriod": 0,
                    "principalOriginalDue": 0,
                    "principalDue": 0,
                    "principalPaid": 0,
                    "principalWrittenOff": 0,
                    "principalOutstanding": 0,
                    "interestOriginalDue": 0,
                    "interestDue": 0,
                    "interestPaid": 0,
                    "interestWaived": 0,
                    "interestWrittenOff": 0,
                    "interestOutstanding": 0,
                    "feeChargesWaived": 0,
                    "feeChargesWrittenOff": 0,
                    "feeChargesOutstanding": 0,
                    "penaltyChargesDue": 0,
                    "penaltyChargesPaid": 0,
                    "penaltyChargesWaived": 0,
                    "penaltyChargesWrittenOff": 0,
                    "penaltyChargesOutstanding": 0,
                    "totalPaidInAdvanceForPeriod": 0,
                    "totalPaidLateForPeriod": 0,
                    "totalWaivedForPeriod": 0,
                    "totalWrittenOffForPeriod": 0,
                    "totalOutstandingForPeriod": 0,
                    "totalInstallmentAmountForPeriod": 0
                },
                {
                    "dueDate": [
                        2024,
                        3,
                        6
                    ],
                    "principalDisbursed": 0,
                    "principalLoanBalanceOutstanding": 48308.330000,
                    "feeChargesDue": 0,
                    "feeChargesPaid": 0,
                    "totalOriginalDueForPeriod": 6730.680000,
                    "totalDueForPeriod": 6730.680000,
                    "totalPaidForPeriod": 0,
                    "totalActualCostOfLoanForPeriod": 2339.010000,
                    "period": 1,
                    "fromDate": [
                        2024,
                        2,
                        5
                    ],
                    "obligationsMetOnDate": null,
                    "complete": false,
                    "daysInPeriod": 30,
                    "principalOriginalDue": 4391.670000,
                    "principalDue": 4391.670000,
                    "principalPaid": 0,
                    "principalWrittenOff": 0,
                    "principalOutstanding": 4391.670000,
                    "interestOriginalDue": 2339.010000,
                    "interestDue": 2339.010000,
                    "interestPaid": 0,
                    "interestWaived": 0,
                    "interestWrittenOff": 0,
                    "interestOutstanding": 2339.010000,
                    "feeChargesWaived": 0,
                    "feeChargesWrittenOff": 0,
                    "feeChargesOutstanding": 0,
                    "penaltyChargesDue": 0,
                    "penaltyChargesPaid": 0,
                    "penaltyChargesWaived": 0,
                    "penaltyChargesWrittenOff": 0,
                    "penaltyChargesOutstanding": 0,
                    "totalPaidInAdvanceForPeriod": 0,
                    "totalPaidLateForPeriod": 0,
                    "totalWaivedForPeriod": 0,
                    "totalWrittenOffForPeriod": 0,
                    "totalOutstandingForPeriod": 6730.680000,
                    "totalInstallmentAmountForPeriod": 6730.68
                }
            ]
        }
    }
}

---

Initiate repayment

POST {{baseUrl}}/api/v2/client/loans/initiate_repayment

Headers

Name	Type	Description
client-id*	string	The client id that was generated
api-key*	string	The secret api key.

Request Body

Name	Type	Description
loan_ref_no*	string	The loan reference number
amount*	number	The loan amount

200: Ok

{
    "data": {
        "loanRef": "1ED0BBA13F",
        "reference": "11a96d2c-e381-4c7b-907f-8de2b180ebfd",
        "accountNumber": "1001608319",
        "bank": "VFD",
        "amount": 20,
        "aggregator_Id": 11,
        "customer_Id": 1140,
        "loanUnits": 1,
        "dateRepaid": "2024-06-12T12:38:32.954041+00:00",
        "repaymentStatus": 2,
        "retryCount": 0,
        "userId": 3122,
        "name": "Lacy Ebert",
        "currency": "NGN",
        "isPaid": 1,
        "message": "",
        "aggregator": "Paelyt",
        "borrowerRepaymentLoans": [
            {
                "loan_Id": 3293,
                "amount": 20,
                "repaymentStatus": 1 // PENDING = 1, SUCCESS = 2, FAILED = 3, CANCELLED = 4
            }
        ]
    },
    "message": "Payment request submitted successfully",
    "status": true,
    "status_code": 200
}

400: BadRequest

{
    "message": "loan with Ref no. 1ED0BBA13F repayment amount 3000 is more than loan repayment balance 2484.89",
    "status": false,
    "status_code": 400
}

---

Generate loan schedule

POST {{baseUrl}}/api/v2/client/loans/generate_loan_schedule

Headers

Name	Type	Description
client-id*	string	The client id that was generated
api-key*	string	The secret api key.

Request Body

Name	Type	Description
productId*	number	The product id
loanTenor*	number	The loan tenor
principalAmount*	number	The principal amount
interest*	number	The loan interest rate
loanEffectiveDate	string	The loan effective date

---

Request Loan

POST {{baseUrl}}/api/v2/client/loans/request_loan

Headers

Name	Type	Description
client-id*	string
api-key*	string

Request Body

Name	Type	Description
identity_number*	string
country_code*	string
product_id*	integer
loan_amount*	integer
loan_tenure*	integer
sector_code*	string
repayment_start_date	string
annual_interest_rate*	string
aggregator_loan_ref	string
loan_purpose*	string
batch_loan_number	string
use_customer_wallet	boolean

---

Loan Status

Meanings and descriptions

Status Code	Meaning of Status Code	Description
500	Rejected	When the loan is rejected
300	Active	When the loan has been disbursed and is currently an active loan
200	Approved	When the loan has been approved and is pending disbursement
600	Closed	When the full cycle of the loan has been completed
100	Submitted and Awaiting Approval	When the loan is still awaiting approval from your end
400	Withdrawn by Client	Flag indicating the money has been withdrawn from your system
601	Written Off	Same as a bad loan
602	Rescheduled	When a loan rollover is done on a specific loan
700	Overpaid	When the repayment has been overpaid