Loans
1.0 AUTHORIZATION
Authorization to the APIs below requires an access token. To get more info on how to generate this access token, click on Generating Access Token
2.0 BASE URL
All requests to the Wallet API in the test environment must be done using the web API URL below.
Test Environment: https://api-devapps.vfdbank.systems/vtech-credit/api/v2/credit
Live Environment: https://api-apps.vfdbank.systems/vtech-credit/api/v2/credit
Also, ensure you call the onboarding endpoint first in the test environment only to ensure your wallet is set up properly after receiving the consumer key, consumer secret .
Note: Accounts created under another wallet can not be accessible under another profile
3.0 HOW TO USE THE LOAN APIs
- The developer first needs to create an account. Reference the WALLET API for more info on how to do this.
- The developer should then call the CREATE AND DISBURSE LOAN api to disburse loan to a wallet account.
- The developer should then call the LOAN TRANSACTION STATUS QUERY api to confirm the status of loan disbursal especially when a 09 response is returned as status after calling the api
- The developer can optionally call the LOAN REPAYMENT SCHEDULE api to get the repayment schedule for a successful loan disbursal
- The developer can also optionally call the LOAN PORTFOLIO api to get details of a loan disbursal like amount disbursed, account no disbursed, etc.
3.1 CREATE AND DISBURSE LOAN
API Context: /loan/create-and-disburse
Description: This endpoint allows you to create and disburse a loan to an account
API METHOD: POST
REQUEST HEADERS
| Key | Value |
|---|---|
| AccessToken | {{token}} |
SAMPLE REQUEST
{
"transactionId":"wallnetname-000192",
"accountNo":"1001552106",
"amount":50000,
"duration":1,
"durationType":"0"
}
| Field | Description | Status |
|---|---|---|
| transactionId | Unique transaction reference, must be prefixed with your wallet name | Mandatory |
| accountNo | account to disburse to | Mandatory |
| amount | amount to disburse | Mandatory |
| duration | loan duration e.g 3 | Mandatory |
| durationType | loan duration type. It can be days(if you pass 0), weeks(if you pass 1) or months(if you pass 2). If the field durationType is not passed, it is set as months by default | Optional |
Sample RESPONSE
{
"status": "00",
"message": "Loan account created and amount disbursed successfully into 1001552106",
"data": {
"loanAccountNumber": "2001552106"
}
}
Sample FAILED RESPONSE
{
"status": "401",
"message": "Not permitted for Loans"
}
3.2 LOAN TRANSACTION STATUS QUERY
API Context: /loan/transactions?identification={identification}
Description: This endpoint allows you to verify the status of a loan transaction
API METHOD: GET
REQUEST HEADERS
| Key | Value |
|---|---|
| AccessToken | {{token}} |
| Field | Description |
|---|---|
| identification | loan transaction id |
SAMPLE RESPONSE
{
"status": "00",
"message": "Successful Transaction Retrieval",
"data": {
"reference": "OdTechWallet2-20101010",
"accountNo": "1000000301",
"loanAccountNo": "2000019320",
"amount": "2000",
"duration": "3",
"disburseDate": "2023-07-12 15:00:10",
"status": "00",
"statusDescription": "Loan Disbursed Successfully"
}
}
3.3 LOAN REPAYMENT SCHEDULE
API Context: /loan/repayment-schedule?identification={identification}
This returns in details the repayment schedule for a particular loan transaction. It also returns the total principal disbursed, total interest charged, totalRepaymentExpected, etc.
Authorization: Bearer Token
API METHOD: GET
QUERY PARAMETERS
| Field | Description | Status |
|---|---|---|
| identification | Transaction Unique Reference | Mandatory |
SAMPLE RESPONSE
{
"status": "00",
"message": "Repayment Schedule for rosapay-11111pqqp3",
"data": {
"repaymentSchedule": {
"currency": {
"code": "NGN",
"name": "Nigerian Naira",
"decimalPlaces": 2,
"inMultiplesOf": 2,
"nameCode": "currency.NGN",
"displayLabel": "Nigerian Naira [NGN]"
},
"loanTermInDays": 91,
"totalPrincipalDisbursed": 50000.00,
"totalPrincipalExpected": 50000.00,
"totalPrincipalPaid": 0.00,
"totalInterestCharged": 1003.32,
"totalFeeChargesCharged": 0.00,
"totalPenaltyChargesCharged": 0.00,
"totalWaived": 0.00,
"totalWrittenOff": 0.00,
"totalRepaymentExpected": 51003.32,
"totalRepayment": 0.00,
"totalPaidInAdvance": 0.00,
"totalPaidLate": 0.00,
"totalOutstanding": 51003.32,
"totalOverdueInterest": 0.00,
"periods": [
{
"dueDate": [
2023,
12,
28
],
"principalDisbursed": 50000.000000,
"principalLoanBalanceOutstanding": 50000.000000,
"feeChargesDue": 0.000000,
"feeChargesPaid": 0.000000,
"totalOriginalDueForPeriod": 0.000000,
"totalDueForPeriod": 0.000000,
"totalPaidForPeriod": 0.000000,
"totalActualCostOfLoanForPeriod": 0.000000
},
{
"period": 1,
"fromDate": [
2023,
12,
28
],
"dueDate": [
2024,
1,
28
],
"complete": false,
"daysInPeriod": 31,
"principalOriginalDue": 16501.000000,
"principalDue": 16501.000000,
"principalPaid": 0,
"principalWrittenOff": 0,
"principalOutstanding": 16501.000000,
"principalLoanBalanceOutstanding": 33499.000000,
"interestOriginalDue": 500.000000,
"interestDue": 500.000000,
"interestPaid": 0,
"interestWaived": 0,
"interestWrittenOff": 0,
"interestOutstanding": 500.000000,
"feeChargesDue": 0,
"feeChargesPaid": 0,
"feeChargesWaived": 0,
"feeChargesWrittenOff": 0,
"feeChargesOutstanding": 0,
"penaltyChargesDue": 0,
"penaltyChargesPaid": 0,
"penaltyChargesWaived": 0,
"penaltyChargesWrittenOff": 0,
"penaltyChargesOutstanding": 0,
"overdueInterest": 0,
"totalOriginalDueForPeriod": 17001.000000,
"totalDueForPeriod": 17001.000000,
"totalPaidForPeriod": 0,
"totalPaidInAdvanceForPeriod": 0,
"totalPaidLateForPeriod": 0,
"totalWaivedForPeriod": 0,
"totalWrittenOffForPeriod": 0,
"totalOutstandingForPeriod": 17001.000000,
"totalOverdue": 17001.000000,
"totalActualCostOfLoanForPeriod": 500.000000,
"totalInstallmentAmountForPeriod": 17001.00
},
{
"period": 2,
"fromDate": [
2024,
1,
28
],
"dueDate": [
2024,
2,
28
],
"complete": false,
"daysInPeriod": 31,
"principalOriginalDue": 16666.010000,
"principalDue": 16666.010000,
"principalPaid": 0,
"principalWrittenOff": 0,
"principalOutstanding": 16666.010000,
"principalLoanBalanceOutstanding": 16832.990000,
"interestOriginalDue": 334.990000,
"interestDue": 334.990000,
"interestPaid": 0,
"interestWaived": 0,
"interestWrittenOff": 0,
"interestOutstanding": 334.990000,
"feeChargesDue": 0,
"feeChargesPaid": 0,
"feeChargesWaived": 0,
"feeChargesWrittenOff": 0,
"feeChargesOutstanding": 0,
"penaltyChargesDue": 0,
"penaltyChargesPaid": 0,
"penaltyChargesWaived": 0,
"penaltyChargesWrittenOff": 0,
"penaltyChargesOutstanding": 0,
"overdueInterest": 0,
"totalOriginalDueForPeriod": 17001.000000,
"totalDueForPeriod": 17001.000000,
"totalPaidForPeriod": 0,
"totalPaidInAdvanceForPeriod": 0,
"totalPaidLateForPeriod": 0,
"totalWaivedForPeriod": 0,
"totalWrittenOffForPeriod": 0,
"totalOutstandingForPeriod": 17001.000000,
"totalActualCostOfLoanForPeriod": 334.990000,
"totalInstallmentAmountForPeriod": 17001.00
},
{
"period": 3,
"fromDate": [
2024,
2,
28
],
"dueDate": [
2024,
3,
28
],
"complete": false,
"daysInPeriod": 29,
"principalOriginalDue": 16832.990000,
"principalDue": 16832.990000,
"principalPaid": 0,
"principalWrittenOff": 0,
"principalOutstanding": 16832.990000,
"principalLoanBalanceOutstanding": 0.000000,
"interestOriginalDue": 168.330000,
"interestDue": 168.330000,
"interestPaid": 0,
"interestWaived": 0,
"interestWrittenOff": 0,
"interestOutstanding": 168.330000,
"feeChargesDue": 0,
"feeChargesPaid": 0,
"feeChargesWaived": 0,
"feeChargesWrittenOff": 0,
"feeChargesOutstanding": 0,
"penaltyChargesDue": 0,
"penaltyChargesPaid": 0,
"penaltyChargesWaived": 0,
"penaltyChargesWrittenOff": 0,
"penaltyChargesOutstanding": 0,
"overdueInterest": 0,
"totalOriginalDueForPeriod": 17001.320000,
"totalDueForPeriod": 17001.320000,
"totalPaidForPeriod": 0,
"totalPaidInAdvanceForPeriod": 0,
"totalPaidLateForPeriod": 0,
"totalWaivedForPeriod": 0,
"totalWrittenOffForPeriod": 0,
"totalOutstandingForPeriod": 17001.320000,
"totalActualCostOfLoanForPeriod": 168.330000,
"totalInstallmentAmountForPeriod": 17001.32
}
]
}
}
}
3.4 LOAN PORTFOLIO
API Context /loan/portfolio?endDate={endDate}&startDate={startDate}&page={page}&size={size}&search={search}&filterBy={filterBy}
Description: This returns details like amount disbursed, account no disbursed to, date disbursed, loan duration, loan duration type, loan status, etc. for all loan transactions or a specific loan transaction.
API METHOD: GET
REQUEST HEADERS
| Key | Value |
|---|---|
| AccessToken | {{token}} |
QUERY PARAMETERS
| Field | Description | Status |
|---|---|---|
| endDate | End date for search e.g 2024-05-22 23:59:59 | Mandatory |
| startDate | Start date for search e.g 2024-05-20 00:00:00 | Mandatory |
| size | Page size | Optional |
| page | Page number starts from 0 | Optional |
| filterBy | FilterBy can be amount, transactionId, status or accountNo | Optional |
| search | Search is filterBy's actual value. e.g if filterBy is amount, search can be 5000 | Optional |
Note: You ony need to pass filterBy and search if you want to return loan portfolio details for a specific transactionId, amount, account no or status.
SAMPLE RESPONSE
{
"status": "00",
"message": "Successful",
"data": {
"content": [
{
"duration": "3",
"disburseDate": "06 October 2023",
"loanAccountNo": "1000090481",
"clientName": "Dan Doe",
"walletName": "rosapay",
"transactionId": "rosapay-01HC2B8FHT0BYY6TYQCQT57GXN",
"status": "00",
"amount": "191000",
"accountNo": "1001191458",
"walletId": "100",
"statusDescription": "Loan Disbursed Successfully",
"interestFrequency": "Per month",
"interest": "1.0",
"durationType": "months"
}
],
"totalElements": 1,
"totalPages": 1
}
}