API ReferenceDeveloper ConsoleDeveloper Community

High Value Loans

Interswitch Lending Services has integrated with data providers to enrich customer transaction information with bank statements currently provided by ILS to lenders. This will enable lenders provide high-value loans without the need for prospective customers having to provide physical documents like financial statements. The following are the features to be derived from this integration.

Suggest Edits

📘

Please Note:

You need to have these endpoints defined on your application - Accept Offers, Get Offers, Get Loan Status, Payment Notification.

Step 1: Fetch the loan offer

Make a post request to the Get Offers endpoint to get a list of the available loan offers.

Request

curl --request GET \
     --url 'https://sandbox.interswitchng.com/lending-service/api/v3/offers?customerId=2348123456789&channelCode=QTUSSD&amount=5000000&serviceType=MONEY&dateOfBirth=1998-08-08&providerCode=MKT' \
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXltZW50Z2F0ZXdheSIsInBhc3Nwb3J0IiwicGF5bWVudC1zZXJ2aWNlIiwicHJvamVjdC14LW1lcmNoYW50IiwidmF1bHQiXSwibWVyY2hhbnRfY29kZSI6Ik1YMTg3IiwicHJvZHVjdGlvbl9wYXltZW50X2NvZGUiOiIwMDE2NDYzOTg1NCIsInJlcXVlc3Rvcl9pZCI6IjAwMTE3NjE0OTkyIiwic2NvcGUiOlsicHJvZmlsZSJdLCJqdGkiOiIzNTFjNDQ5MS01YzcwLTRhOTEtODRiZS0zZjNjY2Q1YzE2Y2MiLCJwYXlhYmxlX2lkIjoiMjMyNCIsImNsaWVudF9pZCI6IklLSUE5NjE0QjgyMDY0RDYzMkU5QjY0MThERjM1OEE2QTRBRUE4NEQ3MjE4IiwicGF5bWVudF9jb2RlIjoiMDQyNTk0MTMwMjQ2In0.P2mUITLA2bsmMryCyuVwDXK-4ozcRYtEKIN1t-qRPZaUStKleLsgxQxJqXv0EZ0CIYbAECw28AeJmbiBtosVSQ824unhfYTyhRCAt1olO_pNwf6PPmMNVTUO5q7F1b3CQPKP5D3VmNMw3MrHUzTzLwqMMzTIAYWf3V-7TEuHBOVzTsOtmuV-j63qASkFGsn_3x-TwgPVeOZ-INnDtXnSCSwQKG10q0_QE7B-ke2v0Up0vxXJ4wTsX8qWm6sJ5Bn_GU260qNPnVCip93xhzAHv7e__ONfeTMdDVPypQ0lyKgcR0FcBrJqONz6yifuu2BfoGeDkXV1cyZFhZg_xwiFYw' \
     --header 'accept: application/json'

Response

{
  "responseCode": "00",
  "responseMessage": "Offers available",
  "offers": [
    {
      "offerId": "FI12345",
      "amountOffered": 1000000, // Ten thousand naira only
      "interest" : 12.5 // In percentage: 12.5%
      "amountPayable": 1250000, // Ten thousand, two hundred and fifty naira only
      "tenure": 30,
      "expiryDate": "2017-05-30T16:49:12Z"
      "currency": "566"
    }
  ]
}

Step 2: Fetch the customer transaction records

When you receive the offer request, use Get Customer Transaction Records to get the customer's bank statement and check if they qualify for a loan.

Request

curl --request GET \
     --url 'https://sandbox.interswitchng.com/lending-service-data-service/api/v1/customer-details/transactions/MIG1234567?offerRequestReference=MIG1234567' \
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXltZW50Z2F0ZXdheSIsInBhc3Nwb3J0IiwicGF5bWVudC1zZXJ2aWNlIiwicHJvamVjdC14LW1lcmNoYW50IiwidmF1bHQiXSwibWVyY2hhbnRfY29kZSI6Ik1YMTg3IiwicHJvZHVjdGlvbl9wYXltZW50X2NvZGUiOiIwMDE2NDYzOTg1NCIsInJlcXVlc3Rvcl9pZCI6IjAwMTE3NjE0OTkyIiwic2NvcGUiOlsicHJvZmlsZSJdLCJqdGkiOiIzNTFjNDQ5MS01YzcwLTRhOTEtODRiZS0zZjNjY2Q1YzE2Y2MiLCJwYXlhYmxlX2lkIjoiMjMyNCIsImNsaWVudF9pZCI6IklLSUE5NjE0QjgyMDY0RDYzMkU5QjY0MThERjM1OEE2QTRBRUE4NEQ3MjE4IiwicGF5bWVudF9jb2RlIjoiMDQyNTk0MTMwMjQ2In0.P2mUITLA2bsmMryCyuVwDXK-4ozcRYtEKIN1t-qRPZaUStKleLsgxQxJqXv0EZ0CIYbAECw28AeJmbiBtosVSQ824unhfYTyhRCAt1olO_pNwf6PPmMNVTUO5q7F1b3CQPKP5D3VmNMw3MrHUzTzLwqMMzTIAYWf3V-7TEuHBOVzTsOtmuV-j63qASkFGsn_3x-TwgPVeOZ-INnDtXnSCSwQKG10q0_QE7B-ke2v0Up0vxXJ4wTsX8qWm6sJ5Bn_GU260qNPnVCip93xhzAHv7e__ONfeTMdDVPypQ0lyKgcR0FcBrJqONz6yifuu2BfoGeDkXV1cyZFhZg_xwiFYw' \
     --header 'accept: application/json'

Response

{
    "_id": "5efc893f46cf550aeda91f41",
    "status": "success",
    "message": "Callback successfully returned!",
    "data": {
        "transactions": [
            {
                "id": "5efc895b46cf550aeda91f47",
                "notes": {
                    "topics": [
                        "c"
                    ],
                    "places": [
                        "c"
                    ],
                    "people": [
                        "b"
                    ],
                    "actions": [
                        "a"
                    ],
                    "subjects": [
                        "b"
                    ],
                    "preopositions": [
                        "a"
                    ],
                    "desc": "Quis ad ratione culpa consequatur sit."
                },
                "fetched": [],
                "owner": [
                    "5edfd8605aa993069041bea4"
                ],
                "record": [
                    "5efc893f46cf550aeda91f41"
                ],
                "branch": "OFMAIMZ1514",
                "code": "c",
                "credit": 98821,
                "customer": "5ef09108658acd0d06ae06b9",
                "env": "production-sandbox",
                "bank": "5d6fe57a4099cc4b210bbeb9",
                "cleared_date": "2020-07-01T12:16:45.728Z",
                "unformatted_cleared_date": "01-07-2020",
                "trans_date": "2020-07-01T09:48:53.173Z",
                "unformatted_trans_date": "01-07-2020",
                "created_at": "2020-07-01T13:02:19.610Z",
                "last_updated": "2020-07-01T13:02:19.610Z"
            },
            {
                "id": "5efc895b46cf550aeda91f45",
                "notes": {
                    "topics": [
                        "b"
                    ],
                    "places": [
                        "b"
                    ],
                    "people": [
                        "c"
                    ],
                    "actions": [
                        "a"
                    ],
                    "subjects": [
                        "a"
                    ],
                    "preopositions": [
                        "a"
                    ],
                    "desc": "Voluptatem ut commodi laudantium repudiandae molestiae numquam consectetur est repellat."
                },
                "fetched": [],
                "owner": [
                    "5edfd8605aa993069041bea4"
                ],
                "record": [
                    "5efc893f46cf550aeda91f41"
                ],
                "branch": "TPNEBEH1",
                "code": "w",
                "credit": 28082,
                "customer": "5ef09108658acd0d06ae06b9",
                "env": "production-sandbox",
                "bank": "5d6fe57a4099cc4b210bbeb9",
                "cleared_date": "2020-06-30T16:17:43.904Z",
                "unformatted_cleared_date": "30-06-2020",
                "trans_date": "2020-06-30T20:33:33.219Z",
                "unformatted_trans_date": "30-06-2020",
                "created_at": "2020-07-01T13:02:19.609Z",
                "last_updated": "2020-07-01T13:02:19.609Z"
            }
    }
}

Step 3 After confirming eligibility, you have two options:

  • Use the Send Offers endpoint if you want to respond to a customer's offer request later, especially when you need additional time to assess their credibility.
  • Alternatively, return an offer immediately using the Accept Offer endpoint if no additional time is required

Request

curl --request POST \
     --url 'https://sandbox.interswitchng.com/lending-service/api/v1/offers/test/send-offers?code=test&message=test&providerCode=test&offers=test&offerId=test&amountOffered=test&interest=test&amountPayable=test&fee=test&tenure=test&terms=test&expiryDate=test&currency=test&isPartPaymentAllowed=true' \
     --header 'Authorization: textr' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer the bearer token'

curl --request POST \
     --url https://sandbox.interswitchng.com/lending-service/api/v1/offers/offerId/accept \
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXltZW50Z2F0ZXdheSIsInBhc3Nwb3J0IiwicGF5bWVudC1zZXJ2aWNlIiwicHJvamVjdC14LW1lcmNoYW50IiwidmF1bHQiXSwibWVyY2hhbnRfY29kZSI6Ik1YMTg3IiwicHJvZHVjdGlvbl9wYXltZW50X2NvZGUiOiIwMDE2NDYzOTg1NCIsInJlcXVlc3Rvcl9pZCI6IjAwMTE3NjE0OTkyIiwic2NvcGUiOlsicHJvZmlsZSJdLCJqdGkiOiIzNTFjNDQ5MS01YzcwLTRhOTEtODRiZS0zZjNjY2Q1YzE2Y2MiLCJwYXlhYmxlX2lkIjoiMjMyNCIsImNsaWVudF9pZCI6IklLSUE5NjE0QjgyMDY0RDYzMkU5QjY0MThERjM1OEE2QTRBRUE4NEQ3MjE4IiwicGF5bWVudF9jb2RlIjoiMDQyNTk0MTMwMjQ2In0.P2mUITLA2bsmMryCyuVwDXK-4ozcRYtEKIN1t-qRPZaUStKleLsgxQxJqXv0EZ0CIYbAECw28AeJmbiBtosVSQ824unhfYTyhRCAt1olO_pNwf6PPmMNVTUO5q7F1b3CQPKP5D3VmNMw3MrHUzTzLwqMMzTIAYWf3V-7TEuHBOVzTsOtmuV-j63qASkFGsn_3x-TwgPVeOZ-INnDtXnSCSwQKG10q0_QE7B-ke2v0Up0vxXJ4wTsX8qWm6sJ5Bn_GU260qNPnVCip93xhzAHv7e__ONfeTMdDVPypQ0lyKgcR0FcBrJqONz6yifuu2BfoGeDkXV1cyZFhZg_xwiFYw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customerId": "2348123456789",
  "offerId": "8288948",
  "destinationAccountNumber": "044",
  "destinationBankCode": "089898998",
  "token": "Tooken",
  "loanReferenceId": "KB9090"
}
'

Response

{
  "responseCode": "00",
  "responseMessage": "Successful. Offer(s) will be sent to the customer."
}

{
  "responseCode": "00",
  "responseMessage": "The customer will be notified accordingly."
}

{ 
“responseCode”: “00”, 
“responseMessage”: “Successful” 
“loanId”:”0329” 
}

Step 4: Verify customer account number

During the process of accepting the loan offer, validate the customer's bank account by making a call to the verify account number endpoint

Step 5: Credit the customer

Provided the customer is eligible for a loan and validation checks have been completed credit the customer.

Request

curl --request POST \
     --url https://sandbox.interswitchng.com/lending-service/api/v1/loans/10000000044/fund \
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXltZW50Z2F0ZXdheSIsInBhc3Nwb3J0IiwicGF5bWVudC1zZXJ2aWNlIiwicHJvamVjdC14LW1lcmNoYW50IiwidmF1bHQiXSwibWVyY2hhbnRfY29kZSI6Ik1YMTg3IiwicHJvZHVjdGlvbl9wYXltZW50X2NvZGUiOiIwMDE2NDYzOTg1NCIsInJlcXVlc3Rvcl9pZCI6IjAwMTE3NjE0OTkyIiwic2NvcGUiOlsicHJvZmlsZSJdLCJqdGkiOiIzNTFjNDQ5MS01YzcwLTRhOTEtODRiZS0zZjNjY2Q1YzE2Y2MiLCJwYXlhYmxlX2lkIjoiMjMyNCIsImNsaWVudF9pZCI6IklLSUE5NjE0QjgyMDY0RDYzMkU5QjY0MThERjM1OEE2QTRBRUE4NEQ3MjE4IiwicGF5bWVudF9jb2RlIjoiMDQyNTk0MTMwMjQ2In0.P2mUITLA2bsmMryCyuVwDXK-4ozcRYtEKIN1t-qRPZaUStKleLsgxQxJqXv0EZ0CIYbAECw28AeJmbiBtosVSQ824unhfYTyhRCAt1olO_pNwf6PPmMNVTUO5q7F1b3CQPKP5D3VmNMw3MrHUzTzLwqMMzTIAYWf3V-7TEuHBOVzTsOtmuV-j63qASkFGsn_3x-TwgPVeOZ-INnDtXnSCSwQKG10q0_QE7B-ke2v0Up0vxXJ4wTsX8qWm6sJ5Bn_GU260qNPnVCip93xhzAHv7e__ONfeTMdDVPypQ0lyKgcR0FcBrJqONz6yifuu2BfoGeDkXV1cyZFhZg_xwiFYw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customerId": "2348123456789",
  "loanId": "10000000044",
  "amount": 5000,
  "providerCode": "PTB",
  "currencyCode": "566",
  "transactionId": "145688247533498",
  "qtTerminalId": "QTB5",
  "loanReferenceId": "Ltb5:9090"
}
'

Response

{
  "responseCode": "00",
  "responseMessage": "Transaction Successful",
  "transactionRef": "UBN|WEB|ILS|20170501091282|01238797",
  "transactionId": "198988747587875"
}

Step 6: Inform the customer of the credit

After updating the loan status of the customer send a message using the send sms endpoint to the customer informing them of the credit. Sometimes, due to flaky internet connectivity or some other factors in which the credit process fails, you can perform a requery to confirm the status of the transaction.

Request

curl --request POST \
     --url 'https://sandbox.interswitchng.com/lending-service/api/v1/sms?providerCode=PTB&customerId=2348123456789' \
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXltZW50Z2F0ZXdheSIsInBhc3Nwb3J0IiwicGF5bWVudC1zZXJ2aWNlIiwicHJvamVjdC14LW1lcmNoYW50IiwidmF1bHQiXSwibWVyY2hhbnRfY29kZSI6Ik1YMTg3IiwicHJvZHVjdGlvbl9wYXltZW50X2NvZGUiOiIwMDE2NDYzOTg1NCIsInJlcXVlc3Rvcl9pZCI6IjAwMTE3NjE0OTkyIiwic2NvcGUiOlsicHJvZmlsZSJdLCJqdGkiOiIzNTFjNDQ5MS01YzcwLTRhOTEtODRiZS0zZjNjY2Q1YzE2Y2MiLCJwYXlhYmxlX2lkIjoiMjMyNCIsImNsaWVudF9pZCI6IklLSUE5NjE0QjgyMDY0RDYzMkU5QjY0MThERjM1OEE2QTRBRUE4NEQ3MjE4IiwicGF5bWVudF9jb2RlIjoiMDQyNTk0MTMwMjQ2In0.P2mUITLA2bsmMryCyuVwDXK-4ozcRYtEKIN1t-qRPZaUStKleLsgxQxJqXv0EZ0CIYbAECw28AeJmbiBtosVSQ824unhfYTyhRCAt1olO_pNwf6PPmMNVTUO5q7F1b3CQPKP5D3VmNMw3MrHUzTzLwqMMzTIAYWf3V-7TEuHBOVzTsOtmuV-j63qASkFGsn_3x-TwgPVeOZ-INnDtXnSCSwQKG10q0_QE7B-ke2v0Up0vxXJ4wTsX8qWm6sJ5Bn_GU260qNPnVCip93xhzAHv7e__ONfeTMdDVPypQ0lyKgcR0FcBrJqONz6yifuu2BfoGeDkXV1cyZFhZg_xwiFYw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "providerCode": "PTB",
  "msisdn": "2348123456789",
  "message": "A message has been sent to you",
  "loanId": "10000000044",
  "customerId": "2348123456789"
}
'

Response

{
  "responseCode": "00",
  "responseMessage": "Successful"
}

Step 7: Collect payment from the customer at the loan due date

To collect payments from the customer make a call to the Debit Customer endpoint

Request

curl --request POST \
     --url https://sandbox.interswitchng.com/lending-service/api/v1/loans/OFFER1598612621100/debit \
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXltZW50Z2F0ZXdheSIsInBhc3Nwb3J0IiwicGF5bWVudC1zZXJ2aWNlIiwicHJvamVjdC14LW1lcmNoYW50IiwidmF1bHQiXSwibWVyY2hhbnRfY29kZSI6Ik1YMTg3IiwicHJvZHVjdGlvbl9wYXltZW50X2NvZGUiOiIwMDE2NDYzOTg1NCIsInJlcXVlc3Rvcl9pZCI6IjAwMTE3NjE0OTkyIiwic2NvcGUiOlsicHJvZmlsZSJdLCJqdGkiOiIzNTFjNDQ5MS01YzcwLTRhOTEtODRiZS0zZjNjY2Q1YzE2Y2MiLCJwYXlhYmxlX2lkIjoiMjMyNCIsImNsaWVudF9pZCI6IklLSUE5NjE0QjgyMDY0RDYzMkU5QjY0MThERjM1OEE2QTRBRUE4NEQ3MjE4IiwicGF5bWVudF9jb2RlIjoiMDQyNTk0MTMwMjQ2In0.P2mUITLA2bsmMryCyuVwDXK-4ozcRYtEKIN1t-qRPZaUStKleLsgxQxJqXv0EZ0CIYbAECw28AeJmbiBtosVSQ824unhfYTyhRCAt1olO_pNwf6PPmMNVTUO5q7F1b3CQPKP5D3VmNMw3MrHUzTzLwqMMzTIAYWf3V-7TEuHBOVzTsOtmuV-j63qASkFGsn_3x-TwgPVeOZ-INnDtXnSCSwQKG10q0_QE7B-ke2v0Up0vxXJ4wTsX8qWm6sJ5Bn_GU260qNPnVCip93xhzAHv7e__ONfeTMdDVPypQ0lyKgcR0FcBrJqONz6yifuu2BfoGeDkXV1cyZFhZg_xwiFYw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customerId": "2348123456789",
  "loanId": "OFFER1598612621100",
  "amount": 5000,
  "providerCode": "MKT",
  "transactionId": "145688247534499"
}
'

Response

{
  "responseCode": "00",
  "responseMessage": "Transaction Successful",
  "transactionRef": "UBN|WEB|ILS|20170501091282|01238797",
  "transactionId": "198988747587875"
}

Step 8: Confirm the loan status and receive notifications

Requests

curl --request GET \
     --url 'https://lender.com/endpoint/10000000058?customerId=2348123456789&loanId=KHIO&providerCode=PTB&channelCode=QTUSSD' \
     --header 'accept: application/json' \
     --header 'password: doe' \
     --header 'username: john'

curl --request POST \
     --url https://lender.com/endpoint \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'password: doe' \
     --header 'username: john' \
     --data '
{
  "loanId": "string",
  "paymentRef": "string",
  "Amount": "string",
  "customerId": "string"
}
'

Response


{
“responseCode”: “00”,
“responseMessage”: “Successful”,
“loan”: {
“status”: “OPEN”,
“remainingAmount”: “0.00”,
“dueDate”: “2017-06-12T11:46:15Z”
}


{ 
  “responseCode”: “00”, 
 “responseMessage”: “Successful”, 
  “loanStatus”: “CLOSED”
}

Updated 28 days ago