Overview

The Interswitch Lending Service (ILS) APIs gives you access to provide value financing option for loans to customers. With the ILS API, lenders can integrate for collections and disbursement of loans.

We authenticate every call to our resources using a combination of HTTP headers. These HTTP Headers must be sent for every call in other to access our resources. This documentation describes how a third-party will integrate with our API, gain indepth knowledge about all it's components and understand how they interrelate.

Sample Requests

Interswitch Lending Service APIs are HTTP based RESTful APIs therefore API request and response format are in JSON. Every API endpoint on this documentation has a sample request and responses next to it. All you need to do is replace the dummy parameters with yours. You can also download our postman collection.

Security Headers

Requests will be sent over HTTPS only. Each request is must also sent using the OAuth 2.0 specification bearer realm.

Sample Code

Find below sample codes implemented in various languages. Feel free to alter the look and feel based on your taste and requirement(s). Remember to alter the links and paths appropriately before uploading to a web server.

Language Resources
Javascript Channel, Providers
Java Channel, Providers
PHP Channel, Providers

Response Code

Please refer to the standard HTTP response codes. Where anything starting with 2XX signifies approved, 4XX means client error and 5XX indicates server error. When the response codes start with 4XX or 5XX, an error object will be returned to explain further the reason for this failure.

Base URL

For every API call, use the base url's in the table below. The Sandbox base url is used for testing while the Production base url is used when you are ready to go live with your product.

Sandbox Production
https://sandbox.interswitchng.com/lending-service/api/v1/ https://api.interswitchng.com/lending-service/api/v1

Authentication

Authenticate your API calls by including your access token in the Authorization header of every request you make. Interswitch utilizes OAuth 2 to facilitate authorization and grants access to an application either on behalf of a user or on behalf of the application itself.

Application Authorization

To get an access token, create a project on the Interswitch Developer Console and obtain the Client ID and Secret Key of the project and encode the them using this format client_id:secret_key using base64encode. Copy the encoded value of your Client ID and Secret Key and make a call to the endpoint below with the Authorization header that contains the word Basic followed by a space and the base64-encoded value. Ensure that you use the Content-Type:application/x-www-form-urlencoded header and finally pass the grant_type=client_credentials in the body of the request.


Endpoint

POST

/passport/oauth/token

Sample Request

import requests
url = "https://sandbox.interswitchng.com/passport/oauth/token"
body = {"grant_type":"client_credentials"}
headers = {
    'authorization': "Basic SUtJQTFCNzU5M0M0NDAyQkM1RTAwQzQ2QUM4QjFDMUNDMEI4NUVFQkIwODg6c2VjcmV0",
    'content-type': "application/x-www-form-urlencoded"}
response = requests.request("POST", url, data=body, headers=headers)
print(response.text)
REQUEST PARAMETERS
Parameters Required Type Description
ClientId Yes String Application key. Navigate to `https://developer.interswitchgroup.com` for your application key
SecretKey Yes String Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret.
grant_type Yes String This must be set to client_credentials

Sample Response (Success)

{ 
  "access_token": "{Your access token}",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "profile",
  "merchant_code": "MX10003",
  "requestor_id": "123588975884",
  "client_name": "kL79ov",
  "payable_id": "359854",
  "jti": "19800d56-3ac6-44c2-b318-8f2ece419840"
}

Sample Response (Failure)

{ 
  "code": "Unauthorized",
  "description": "Bad credentials",
  "errors": null
}
RESPONSE PARAMETERS
Parameters Description
access_token A new access token that is used to authenticate against resources that belong to the app itself.
token_type Always bearer
expires_in The lifetime of the access token, in seconds

Authorization headers should be in the following format: Authorization: Bearer Encoded(clientId:secreteKey).


Providers

Integration Flow

Offers

The process flow for Offers is expalined below:

  1. Get Customer Information (Optional): This should be done if the provider needs to get customer details like name, email, etc.
  2. Get Customer History (Optional): This is retrieves the customer transaction history.
  3. Get offers/Get Merchant Offers: This is used to retrieve a list of offers that lenders/loan providers has made available to the customer.

Get Customer Information

This endpoint will be used by providers to retrieve information of a customer from the Platform.

Base Url

https://sandbox.interswitchng.com

Headers

Content Type:application/json
Authorization:InterswitchAuth SUifhfjdbxbkfhj132hdfhjshfjhsv
Signature:kuTwggg/3gdgdghs=
Timestamp:1434455667788
Nonce:7333394444423754333
SignatureMethod:SHA1

Endpoint

GET

{{base url}}/api/v1/payment/history/info?msisdn={{customerId}}

Sample Response (success)

{   
    "responseCode": "00",
    "responseMessage": "Successful",
    "msisdn": "2348035459308",
    "firstName": "Ayinla",
    "lastName": "Omowura",
    "email": "[email protected]",
    "hashedMsisdn": "DBA29C79EED1E6AC388E03AD77E4C748AA87EEC3"
}

Sample Response (failure)

{
    "responseCode" : "5000",
    "responseMessage" : "Error while processing request. Please try again."
}
Request parameter Field Description
Field Name Data Type Max Length Required Description
responseCode String 5 true The code indicating the result of the processing of this request.
responseMessage String 255 true The Description of the responseCode.
msisdn 20 The MSISDN of the Customer.
firstName 50 The First Name of the Customer.
lastName 50 The Last Name of the Customer
email 50 The Email Address of the Customer
hashedMsisdn 100 The Hashed MSISDN of the Customer.


Get Customer History

This endpoint will be used by providers to retrieve information of a customer from the Platform.Please note that, currently, this request will be pass to ESB Service and not ILS Service.

Base Url

https://sandbox.interswitchng.com

Headers

Authorization: InterswitchAuth SUtJQUYzRDNGMkQyMEY1MTM2REVGNUExMjUwMzZDN0U0QjgzMzgwQjBGMjA=
Signature: jTeXolQsXeK07co437g8nB3Yiss=
SignatureMethod: SHA1
Timestamp: 1488814792
startDate: 2017-01-23
endDate: 2017-03-12
mobile: 2348012345768
Nonce: 9fd167a37db1813ef9da661ea481fc3b

Endpoint

GET

{{base url}}/api/v1/payment/history
Request Header Description
Field Name Data Type Max Length Required Description
mobile String 50 true The ID of the customer whose Information the provider is trying to get.
startDate Date String (UTC) 10 true The Date from which history will be retrieved. Format: yyyy-mm-dd
endDate Date String (UTC) 10 true The Date to which history will be retrieved Format: yyyy-mm-dd.

Sample Response (success)

{firstName: IKECHUKWU,
lastName: ONYEKANNA,
email: onyekannaikechukwu@yahoo.com,
mobile: 2348060765123,
cards: [
{bank: Ecobank Nigeria Plc,
maskedPan: 506100*********8508,
trxns: {
WEB: {
Web_Purchase: [{
accountNumber: 5061000205026368508,
acquirerBank: First City Monument Bank Plc,
amount: 7000.00,
cardBrand: Verve,
issuerBank: Ecobank Nigeria Plc,
merchantBiller: 635970849187100444 www.swiftng.cLANG,
pan: 506100*********8508,
paymentItem: Swift Networks Web Payments,
responseCode: 00,
retrievalReference: 000632677710,
transactionDate: 2016-04-24,
transactionTime: 08:55:49}

Sample Response (failure)

{"errors": [
{"code": "E38",
"message": "A search parameter must be provided"}],
"error": {
"code": "E38",
"message": "A search parameter must be provided"}}


Response Message Field Description
Field Name Data Type Max Length Required Description
responseCode Numeric String 5 true The code indicating the result of the processing of this request.
responseMessage String 255 true The Description of the responseCode.
firstName 50 The First Name of the Customer.
lastName 50 The Last Name of the Customer
email 50 The Email Address of the Customer
cards String 50 Array of Cards used for the payments and the respective payments.
bank String 50 The Name of the Bank of the Card.
maskedPan String 100 Masked PAN of the Card.
trxns String An object having properties representing the transactions done on the card, the channel from which they are done and the type of transaction that they are.
accountNumber Numeric String 20
acquirerBank Numeric String 50
cardBrand String 20 The Branch/Type of the Card (e.g Verve).
issuerBank String 50 The Name of the Bank of the Card.
merchantBiller String
pan String 20
paymentItem String 20 The Item for which the transaction is for (what was paid for with the transaction).
retrievalReference String 50
transactionDate Date String (UTC) 10 The Date on which the transaction is done.
transactionTime Date time 10 The Time at which the transaction is done.
amount Numeric String 20 The amount is in Naira. (6 decimal places)


Get Offers

During the Get Offer processing, a request will be sent from Interswitch Lending Service to Provider to get the offers the Provider has for a User.

Request Message Description
Field Name Data Type Max Length Required Description
customerId String 50 true The Email or Mobile Number of the User who is accepting this offer.
channelCode String 50 true The Code of the Channel from which request is coming from.
amount Long false The Amount of Loan that the Customer wish to take. This can be used to determine the offers that will be returned.
currentLoanStatus Boolean true A Status stating whether the Customer has a current loan in service or not.
hashedCustomerId String 100 true The hashed value of the customer Id, which can be used to retrieved customer data.


Endpoint

GET

/{{endpoint goes here}}

Headers

Authorization : Basic ZXNiasfsd323b3JkMSQ=

The username and password should be provided by the Lender which will be used in generating the basic authorization above

Query Parameters

"customerId": "2348123456789",
"channelCode": "FBNILS",
"amount": "100000", //One thousand naira only
"currentLoanStatus": "True",
"hashedCustomerId": "DBA29C79EED1E6AC388E03AD77E4C748AA87EEC3"

Sample Response (success)

{
  responseCode: 00,
  responseMessage: Successful,
  offers:[{
  offerId: OFFER1553510121100,
  amountOffered: 100000,
  interest: 10.00,
  amountPayable: 110000,
  fees: [{
  name: Tax,
  amount: 100}],
  tenure: 30,
  terms: Please read the terms and conditions on https://onefi.com/terms”,
  currency: 566,
  expiryDate: 2017-06-30T10:24:09Z}

Sample Response (Failure)

{ 
  "responseCode": "3001",
  "responseMessage": "Sorry, we have no loan offers for this customer."
}


Response Message Field Description
Field Name Data Type Max Length Required Description
responseCode Numeric String 5 true The Code representing the status of the processing of the request. It shows whether the request to accept the offer is allowed or not.
responseMessage String 255 true The Description of the Response Code from above.
offers Array true Arrays of Offers that the provider has for the user.
offerId Numeric String 50 True The id representing this offer from the provider..
amountOffered Long True The Amount of this loan offer
interest Numeric String 3 True The interest in percentage attached to the loan
amountPayable Long True The Amount expected to be paid by the User for the loan.
fees Array False The Array of fees that are attached to the loan.
name String 50 True The name of the fees.
amount Long True The amount for the fees.
terms String 100 True The Terms and Conditions attached to the loan offer.
tenure Numeric String True The Time duration of this loan after which the user is expected to pay back the amountPayable (in days)
expiryDate Date Time (UTC) True The Date/Time at which this loan offer expires and become invalid.
currency Numeric String 3 True The Currency of the Amount offered.
isPartPaymentAllowed Boolean True A Boolean depicting whether the Customer is allowed to make part-payment to serve the loan.


Get Merchant Offer

During the Get Offer processing, a request will be sent from Interswitch Lending Service to Provider to get the offers the Provider has for a User.

Request Message description

Field name Data type Max length Required Description
customerId String true The Email or Mobile Number of the User who is accepting this offer.
amount Long false The Amount of Loan that the Customer wish to take. This can be used to determine the offers that will be returned.
currentLoanStatus Boolean true A Status stating whether the Customer has a current loan in service or not.
hashedCustomerId String true The hashed value of the customer Id, which can be used to retrieved customer data.
merchantId String true The originating merchant ID
itemDescription String true Description of item customer is taking a loan for
bvn String true The customer's bank verification number
name String false The requesting customer's name

Endpoint

nothing here

Sample Request

?customerId=2348123456789&amount=100000&currentLoanStatus=false&hashedCustomerId=DBA29C79EED1E6AC388E03AD77E4C748AA87EEC3&merchantId=3IPG001&itemDescription=10KVA generator&bvn=1000000001

Response Message Field Description

Field Description
responseCode The Code representing the status of the processing of the request. It shows whether the request to accept the offer is allowed or not.
responseMessage The Description of the Response Code from above.
offers Arrays of Offers that the provider has for the user.
offerId The Id representing the offer from the provider.
amountOffered The Amount of this loan offer. This is expected to be in the minor denomination (Long value).
interest The interest in percentage attached to the loan
amountPayable The Amount expected to be paid by the User for the loan. This is expected to be in the minor denomination (Long value).
fees The Array of fees that are attached to the loan.
tenure The Time duration of this loan after which the user is expected to pay back the amountPayable (in days).
terms The Terms and Conditions attached to the loan offer.
expiryDate The Date/Time at which this loan offer expires and become invalid.
currency The Currency of the Amount offered.
isPartPaymentAllowed A Boolean depicting whether the Customer is allowed to make part-payment to serve the loan.
description Description of the offer. This will be displayed to the customer
type Possible values of type is ONEOFF and INSTALLMENTS
initialPayment The down payment the customer is expected to pay.
noOfInstallments For an installmental type offer, the number of installments expected

Sample Response (Success)

{
    "responseCode": "00",
    "responseMessage": "Successful",
    "offers": [
        {
            "offerId": "0001",
            "amountOffered": 100000,
            interest"": 10,
            "amountPayable": 110000,
            "fees": [{
                "name": "Tax",
                "amount": 100
            }],
            "tenure": 30,
            "terms": "Please read the terms and conditions on https://onefi.com/terms",
            "expiryDate": "2017-06-12T11:46:15Z",
            "currency": "566",
            "description": "N1000 to pay back N1100 in 3 installments",
            "type" : "INSTALLMENTS",
            "initialPayment" : 1000,
            "noOfInstallments" : 2
        },
        {
            "offerId": "0002",
            "amountOffered": 1000000,
            interest"": 12.5,
            "amountPayable": 1250000,
            "fees": [{
                "name": "Tax",
                "amount": 1000
            }],
            "tenure": 60,
            "terms": "Loanee are expected to have served the loan at the tenure end. Any defaulters of this will likely not be given any loan offer from here or other credit company.",
            "expiryDate": "2017-06-12T11:46:15Z",
            "currency": "566",
            "type" : "ONEOFF",
            "initialPayment" : 0
        }
    ]
}

Sample Response (failure)

{
  "responseCode":"102",
  "responseMessage":"Sorry, we have no loan offers for this customer."
}

Hosted Field

With Hosted Fields, Merchants that are not PCI DSS certified can still integrate with the Interswitch Lending Service.

We built different demo's on how to integrate with the ILS API with Hosted fields. Find the demo's below:

The following fields PAN, Expiry Date, PIN, CVV, OTPare are hosted securely in iframes to enable merchants to embed it on their checkout page.

Setup

Follow the steps below to setup hosted field on your checkout page:

Step 1: Set up your SDK as shown below:

Javascript

<script src="https://mufasa-qa.interswitchng.com/p/lending-service/tokenize/sandbox/build.js"></script>

// This script above should be used if you want to enable tokenization.

Javascript

<script src="https://mufasa-qa.interswitchng.com/p/lending-service/accept/sandbox/build.js"></script>

// This script above should be used if you don't want to enable tokenization. 

The global interswitch.hostedFields variable will be available once you load the Javascript SDK.


Step 2: Create a hosted field instance calling the newInstance method on the interswitch.hostedFields variable. The method should take options and a callback. An hosted field instance which can be used to register events listeners and finally submit the customer's request when the customer clicks on a the submit button will be returned to the callback

Javascript

interswitch.hostedFields.newInstance(options,
  function (err, hostedFieldInstance) {
    if (err) {
      // something is wrong,
      return;
    }
    function findLabel(field) {
      return $('.hosted-field--label[for="' + field.container.id + '"]');
    }
    hostedFieldInstance.on('focus', function (event) {
      var field = event.fields[event.emittedBy];
      findLabel(field).addClass('label-float').removeClass('filled');
    })
  })

The options include authorization, accept offer (whether value financing or regular loans) request, fields and styles as shown below.

Javascript

var options = {
  authorization: "eyJhbGciOiJSUzI1NiJ9eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImZp"
  request: {
    channelCode: "QTUSSD",
    customerId: "2348030583962",
    offerId: "OFFER1529932588104",
    providerCode: "MKT",
    transactionRef: "ab1cfgkhfgvr2",
    merchantCode: "VNA", // merchantCode is only required for Value Financing loans.
    creditMethod: {
        accountNumber: "1234567890",
        bankCode: "056"
    } // creditMethod is only required for Regular Nano Loans.
  },
  styles: {
    'input': {
      'font-size': '16px',
      'font-family': 'roboto, verdana, sans-serif',
      'color': 'black'
    },
    ':focus': {
      'color': 'blue'
    },
    '.valid': {
      'color': 'black'
    },
    '.invalid': {
      'color': 'red'
    }
  },
  fields: {
    pan: {
      selector: '#card-pan',
      placeholder: '1111 1111 1111 1111'
    },
    cvv: {
      selector: '#card-cvv',
      placeholder: '111'
    },
    exp: {
      selector: '#expiration-date',
      placeholder: 'MM/YY'
    },
    pin: {
      selector: '#card-pin',
      placeholder: 'PIN'
    },
    otp: {
      selector: '#card-otp',
      placeholder: 'OTP'
    }
  }

The accept offer request body varies depending on the type of loans your customers apply for. Example: If your customer is requesting for value financing then use merchantCode. If your customer is requesting for regular loans, then use creditMethod. For any other loan type, channelCode, customerId, offerId, providerCode and transactionRef are always required.


Step 3: As soon as the customer submits, initiate a submit request on the hostedFieldInstance returned in 2 as seen in the sample code below.

JavaScript

var submit = document.querySelector('button[type="submit"]');
submit.addEventListener('click', function (evt) {
  evt.preventDefault();
  evt.stopPropagation();
  hostedFieldInstance.submit(function (err, payload) {
     if (err) {
        if (err.responseMessage) {
          alert(err.responseMessage);
          return;
        }
        else if (err.message.body) {
          alert(JSON.stringify(err.message.body.token ? err.message.body.token : err.message.body.errors[0]['message']));
          return;
        }
        else {
          alert(err.message);
          return;
        }
     }
     else if (payload) {
       console.log(payload);
       alert(JSON.stringify(payload.body));
       return;
     }
  });
}, false)

Integration

To start using Hosted Fields, you need to create a basic HTML checkout form. You will need to define containers that will hold the iframe input fields for the following inour fields (Card Number, Expiry Date, CVV, PIN, OTP). Here is a sample form that uses Hosted Fields.

Custom WebPay Hosted Field

See the Pen Custom WebPay Hosted Field by Edidiong Asikpo (@edyasikpo) on CodePen.


Credit Score

Base Url

https://sandbox.interswitchng.com/credit-score-engine/v1

Headers

{
    Content-Type: application/json
    Authorization: { passport generated bearer token }
}

Get Credit Score

This endpoint returns the customer's current credit score generated by the Credit Score Engine for the customer.

Endpoint

GET

{{base url}}/credit-score?msisdn={customer msisdn}

Sample Request

https://sandbox.interswitchng.com/credit-score-engine/v1/credit-score?msisdn=2348070000100


Request Message Description
Field Name Data Type Max Length Required Description
msisdn String 13 true The Phone number(MSISDN) of the customer whose credit score we are trying to retrieve


Response Message Field Description
Field Name Description
responseCode Response code from the API
responseMessage The description of the response code.
score The numerical value of the generated credit score.
dateCreated The date the credit score was generated.


Sample Response (success)

 {
    "responseCode": "00",
    "responseDescription": "Successful",
    "creditScores": [
        {          
            "msisdn": "08077777777",
            "score": "40",
            "dateCreated": "2018-07-10"
        }
    ]
}

Sample Response (failure)

{
    "responseCode":"4004",
    "responseMessage":"No Credit Score."
}

Get Credit Score History

This endpoint returns the customer’s historical credit scores generated by the Credit Score Engine for the customer.

Endpoint

GET

{{base url}}/credit-score/history?msisdn={customer msisdn}

Sample Request

https://sandbox.interswitchng.com/credit-score-engine/v1/credit-score/history?msisdn=2347013217426


Request Message Description
Field Name Data type Max length Required Description
msisdn String 13 true The Phone number(MSISDN) of the customer whose credit score we are trying to retrieve


Sample Response (Success)

Sample Request

{
    "responseCode": "00",
    "responseDescription": "Successful",
    "creditScores": [
        {
            "msisdn": "08077777777",
            "score": "40",
            "dateCreated": "2018-07-10"
        },
        {
            "msisdn": "08077777777",
            "score": "30",
            "dateCreated": "2018-07-05"
        }
    ]
}

Sample Response (Failure)

Sample Request


{
    "responseCode":"4004",
    "responseMessage":"No Credit Score."
}


Response Message Field Description
Field Name Description
responseCode Response code from the API.
responseMessage The description of the response code.
score The numerical value of the generated credit score.
dateCreated The date the credit score was generated.
msisdn Customer phone number.


Salary Lending Service

Base Url

https://sandbox.interswitchng.com

Headers

{
    Content-Type: application/json
    Authorization: { passport generated bearer token }
}

Get Salary Info

This endpoint will be used by providers to retrieve salary information of a customer.

Endpoint

GET

{{base url}}/salary-lending-service/api/v1/salaries

Sample Request

?startDate=2018-04-11&endDate=2018-04-12&pageNumber=1&pageSize=50 &providerCode=SAL-SAN-01


Request parameter Field Description
Field Name Data Type Max Length Required Description
startDate DateString 10 true start date for the date range to search using date format yyyy-MM-dd
endDate Date String 10 true end date for the date range to search using date format yyyy-MM-dd
pageNumber Numeric true
pageSize Numeric true
providerCode String 10 true The Code of the Provider from which offers will be retrieved


Sample Response (success)

[{"employerName":"ABC Transport",
  "accountNumber":"D81B9CB81AE2",
  "bankName":"Second Bank of Nigeria",
  "cbnBankCode":"SBN",
  "msisdn":"43FB02B2429B5CE50D81B9CB81AE23",
  "amount":23500000, // Two hundred and thirty five thousand naira
  "period":"Jan-2018"},
{"employerName":"ABC Transport",
  "accountNumber":"D81B9CB81AE2",
  "bankName":"Second Bank of Nigeria",
  "cbnBankCode":"SBN",
  "msisdn":"43FB02B2429B5CE50D81B9CB81AE23",
  "amount":4300000000 // Fourty three million naira
  "period":"Feb-2018"}]

Sample Response (failure)

{"responseCode" : "10400 ",
"responseMessage" : "Page Number is required."} 

Get Salary Info Count

This endpoint will be used by providers to retrieve volume of customer transaction.

Endpoint

GET

{{base url}}/salary-lending-service/api/v1/salaries/info

Sample Request

?startDate=2018-04-11&endDate=2018-04-12 &providerCode=SAL-SAN-01


Request Parameter Field Description
Field Name Data Type Max Length Required Description
startDate Date String 10 true start date for the date range to search using date format yyyy-MM-dd
endDate Date String 10 true end date for the date range to search using date format yyyy-MM-dd
providerCode String true The Code of the Provider from which offers will be retrieved


Response Message Description
Field Name Data Type Max Length Description
recordCount Numeric


Sample Response (success)

{
    "recordCount":"2300"
}

<div class='payment-token-header'>
<p class='payment-token-header-label'>Sample Response (failure)</p>
</div>

{ "responseCode" : "10500 ", "responseMessage" : "Something went wrong. Please try again" } ```

Offers

This endpoint will be used by providers to create loan offer notification to the customer.

Endpoint

POST

{{base url}}/salary-lending-service/api/v1/offers

Request Message Description
Field Name Data Type Max Length Required Description
msisdn String 40 true The MSISDN of the Customer.
message String 160 true Notification message to be sent to the customer.

Sample Response (Success)

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

Sample Response (failure)

{
    "responseCode" : "10400 ",
    "responseMessage" : "Message length must not exceed 160 characters."
} 

Activate

This endpoint will be used by providers to add customer to a repayment cycle.

Endpoint

POST

{{base url}}/salary-lending-service/api/v1/customers/activate

Request Message Description
Field Name Data Type Max Length Required Description
msisdn String 40 true The MSISDN of the Customer.
activationDate DateString 10 true date of activation using date format yyyy-MM-dd.
loanId String 40 true The Id of loan being served.
providerCode String 10 true The Code of the Provider from which offers will be retrieved.

Sample Post Request

{
    "msisdn":"E5DED0A86647CE7EB02C4C40383EC2",
    "loanId": "119094893843LN",
    "activationDate":"2020-01-17",
    "providerCode" : "SAL-SAN-01"
}

Sample Response (success)

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

Sample Response (failure)

{
    "responseCode" : "10403 ",
    "responseMessage" : "Loan repayment entry already exists for msisdn (CA1EE1BB25211FA73C2566600F0AFA) and loan Id (119094893843LN) "
}

Deactivate

This endpoint will be used by providers to remove customer to a repayment cycle.

Endpoint

POST

{{base url}}/salary-lending-service/api/v1/customers/deactivate

Request Message Description
Field Name Data Type Max Length Required Description
msisdn String 40 true The MSISDN of the Customer.
deactivationDate String 10 true date of activation using date format yyyy-MM-dd.
loanId String 40 true The Id of loan being served.
providerCode String 10 true The Code of the Provider from which offers will be retrieved.

Sample Request

{   
    "msisdn":"E5DED0A86647CE7EB02C4C40383EC2",
    "loanId": "119094893843LN",
    "deactivationDate":"2020-01-17",
    "providerCode" : "SAL-SAN-01"
} 

Sample Response (success)

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

Sample Response (failure)

{
    "responseCode" : "10403 ",
    "responseMessage" : "Deactivation date can not be less than activation date of this loan."
}

Quickteller Value Financing

Get All Merchants

This method retrieves all registered billers and merchants on Quickteller and IPG platforms


Request Message Description
Field Name Data type Required Description
providerCode String true The unique code of the provider sending the request


Endpoint

GET

lending-service/api/v1/merchants

Headers

{
    Content-Type: application/json
    Authorization: { passport generated bearer token }
}


Request Message Description
Field Name Field Description
merchantSource This is the source where merchant info is registered (quickteller or ipg)
categoryid Merchant's category identifier
categoryname Merchant's category name
categorydescription Description of Merchant's Category
merchantCode Merchant's Unique identifier
merchantName Name of merchant
customerfield1 Customer Id Field 1
customerfield2 Customer Id Feld 2
currencySymbol Currency
logoUrl URL of merchant's logo


Sample Response(Success)

{
    "responseCode": "00",
    "responseMessage": "Merchants available",
    "merchants": [
        {
            "merchantSource": "Quickteller,"
            "categoryid": 3, 
            "categoryName" : "State Payment," 
            "categoryDescription": "Pay your taxes", 
            "merchantCode": "LSG",
            "merchantName": "Lagos State Development Agency",
            "customerfield1": "Customer No",
            "customerfield2": "",
            "logourl": "lsg.png"
        }
    ]
}

Sample Response(Failure)

{
    "responseCode": "404",
    "responseMessage": "No available merchants"
}

ILS Data Service

Customer Information

This documentation explains customer information retrieval using the ILS data service API.

Endpoint

GET

/api/v1/customer-info

Headers

{
    Content-Type: application/json
    Authorization: { passport generated bearer token }
}


Request Query Description
Field Name Data Type Max Length Required Description
msisdn String 13 true Mobile number of the customer. Format is 234xxxxxxxxxx.


Sample Request

?msisdn=2348051233455


Request Message Description (Success)
Field Name Data Type Description
responseCode String The Code representing the status of the processing of the request. It shows whether customer information retrieval was successful or not.
responseMessage String The Description of the Response Code from above.
msisdn String Customer's mobile number.
firstName String Customer's first name.
lastName String Customer's last name.
email String Customer's email address.
hashedMsisdn String Hashed customer mobile number.
encryptedPan String Encrypted  customer pan.
dateOfBirth String Customer's date of birth.
bvn String Customer's Bank Verification Number (BVN).
address String Customer's address of residence.
addressCity String Customer's city of residence.
addressState String Customer's state of residence.
accountNumber String Customer's account number.
bankCode String Customer's bank code.
gender String Customer's gender.


Sample Success Response

{
    "responseCode": "00",
    "responseMessage": "Successful",
    "msisdn": "2348051233455",
    "firstName": "CIROMA",
    "lastName": "ADEKUNLE",
    "email": "[email protected]",
    "hashedMsisdn": "8936009DC8E6F452300334374D3C9C14",
    "encryptedPan": "N/A",
    "dateOfBirth": "10/10/1990",
    "bvn": "2354343575654435467453322",
    "address": "NO.1, KOLAQ CLOSE, D, DOMA",
    "addressCity": "IDDO",
    "addressState": "LAGOS",
    "accountNumber": "1112223421",
    "bankCode": "080",
    "gender": "FEMALE"
}


Request Message Description (Failure)
Field Name Data Type Description
responseCode String The Code representing the status of the processing of the request. It shows whether customer information retrieval was successful or not.
responseMessage String The Description of the Response Code from above.


Sample Response (Customer Not Found)

{
    "responseCode": "404",
    "responseMessage": "Customer not found"
}

// This response is returned when there's no customer information in the data source attached to the "msisdn" in the request query.

Sample Response(Unauthorized Access)

{
    "responseCode": "403",
    "responseMessage": "Access not Granted"
}

// This response is returned when there's no authorization token in the header of the request.

Sample Response(Invalid Token)

{
    "responseCode": "403",
    "responseMessage": "Invalid token"
}

// This response is returned when the authorization token in the header is invalid or incorrect.

Sample Response(Wrong MSISDN Format)

{
   "responseCode": "104",
   "responseMessage": "Wrong msisdn"
}

// This response is returned when the msisdn in the request query is not in the right format -- 234xxxxxxxxxx.