Retrieve Clear MSISDN

This endpoint enables the caller to call interswitch with a given hashed msisdn so that he can retrieve the clear phone number given that the record exists on interswitch IDS platform.

Request Data Description

#	Field Name	Data Type	Max Length	Required	Description
1	msisdn	String	50	Yes	This field accept a string of character representing an hashed msisdn that we seek to retrieve the clear msisdn for

Endpoint

{{baseurl}}{{ilsbase}}/verify?msisdn=44D3DCDA61B2AB7A39C61D2B964B2A

NOTE: The msisdn in the url is the hashed msisdn that the caller want to retrieve a clear msisdn for

Headers:

HTTP Method: GET

Authentication: User Access Token or Client Access Token

Content-Type: application/json

Response: { “responseCode”: “00”, “responseMessage”: “Successful”, “data”: { “msisdn”: “2348054930703” } }

4.2 Retrieve details an account and bvn  combination owner

Description:  Given the details itemized in the table below, confirm if the supplied BVN and account Number belong to the same entity and retrieve the details of the entity/account-owner

#	Field Name	Data Type	Max Length / Format	Required	Description
1	bvn	Integer	11	YES	The 11 digit individually unique BVN number to be validated
2	bank-code	integer	3	Yes	The 3 digit unique bank-code assigned by CBN to identify a bank
3	account	Integer		Yes	The bank account number belonging to the bank-code to be validated against the BVN provided

Endpoint

{{baseurl}}/api/v1/request/verification/bvn/{{bvn}}/bank-code/{{bank-code}}/account/{{account-number}}

Sample request call:

{{baseurl}}/api/v1/request/verification/bvn/22355202908/bank-code/058/account/0261642240

Headers:

HTTP Method: GET

        Authorization: Bearer ACCESS_TOKEN

SUCCESS RESPONSE

Description

#	Field Name	Data Type	Description
1	responseCode	String	The code representing the state of the response, it show whether the response was a success or not. NB: “00” is the code for success
2	responseMessage	String	The description that explains the responseCode from above
3	data	Object	The section that contains the account owner details
4	bvn	String	BVN of the owner of the account, would always be same as the BVN supplied in the request if it was successful
5	accountNumber	String	Account number of the owner of the account, would always be same as the account number supplied in the request if it was successful
6	bankCode	String	The bankcode used to identify the bank, would always be same as the bank-code supplied in the request if it was successful
7	accountName	String	Full names of the account holder
8	dob	String	The account holder date of birth (Format: dd-MMM-yy)
9	firstName	String	The account holder’s first name
10	lastName	String	The account holder’s last name
9	phone	String	The account holder’s mobile phone number
10	residentialAddress	String	The account holder’s residential address

Success sample response

Response :{ “responseCode”: “00”,     “responseMessage”: “Successful”,      “data”: { “bvn”: “22292083231”, “accountNumber”: “0696363603”, “accountName”: “MICHEAL SYDENY EDE”, “bankCode”: “044”, “firstName”: “MICHEAL”, “lastName”: “EDE”, “dob”: “12-Mar-75”, “phone”: “08064088818”, “residentialAddress”: “SHEHU AUDI RESIDENCE, FUNTUA STREET, KAFANCHAN”      } }

FAILURE RESPONSE

Description

#	Field Name	Data Type	Description
1	responseCode	String	The code representing the state of the response, it show whether the response was a success or not. NB: “00” is the code for success
2	responseMessage	String	The description that explains the responseCode from above

Failure sample response

Response :{     “responseCode”: “10404”,     “responseMessage”: “No Information Found – No Information Found For Account Details”, }

4.3 Validate an account and bvn  combination

Description:  Given the details itemized in the table below, confirm if the supplied BVN and account Number belong to the same entity

#	Field Name	Data Type	Max Length / Format	Required	Description
1	bvn	Integer	11	YES	The 11 digit individually unique BVN number to be validated
2	bank-code	integer	3	Yes	The 3 digit unique bank-code assigned by CBN to identify a bank
3	account	Integer		Yes	The bank account number belonging to the bank-code to be validated against the BVN provided

Endpoint

{{baseurl}}/api/v1/request/validate/bvn/{{bvn}}/bank-code/{{bank-code}}/account/{{account-number}}

Sample request call:

{{baseurl}}/api/v1/request/validate/bvn/22355202908/bank-code/058/account/0261642240

Headers:

HTTP Method: GET

        Authorization: Bearer ACCESS_TOKEN

SUCCESS RESPONSE

Description

#	Field Name	Data Type	Description
1	responseCode	String	The code representing the state of the response, it show whether the response was a success or not. NB: “00” is the code for success
2	responseMessage	String	The description that explains the responseCode from above
3	data	Object	The section that contains the actual data requested by the request
4	type	String	Description of what is verification status is for
5	isVerified	String	returns either a YES or NO, signifying if the supplied BVN and AccountNumber has a match and both belong to the same entity

Success sample response

Response :{     “responseCode”: “00”,     “responseMessage”: “Successful”,      “data”: {          “type”: “BVN and AccountNumber validation”,          “isVerified”: “YES”      } }

FAILURE RESPONSE

Description

#	Field Name	Data Type	Description
1	responseCode	String	The code representing the state of the response, it show whether the response was a success or not. NB: “00” is the code for success
2	responseMessage	String	The description that explains the responseCode from above

Failure sample response

Response :{     “responseCode”: “10404”,     “responseMessage”: “No Information Found – No Information Found For Account Details”, }

4.4 Validate an individual

Description:  Given validation type and validation ID, and other details itemized in the table below, confirm that a person exist on the KYC platform. The system will confirm the details specified in the request body,  and will also return a response with details based on the validation on the platform. A sample request and response for this call is available below: 

#	Field Name	Data Type	Max Length / Format	Required	Description
1	validationType	String		YES	The type of identification means that is been used to verify the individual, can be one of either NIN, BVN
2	validationId	String		Yes	The unique identification number for that validationType that should point to that unique individual being verified
3	firstname	String		Yes	The firstName of the individual to be vetted against the firstName of the validation ID holder on the KYC platform
4	lastname	String		Yes	The lastName of the individual to be vetted against the lastName of the validation ID holder on the KYC platform
5	birthDate	Date	yyyy-MM-dd	Yes	The date of birth of the individual to be vetted against the date of birth of the validation ID holder on the KYC platform
6	gender	String		Yes	The gender of the individual to be vetted against the gender of the validation ID holder on the KYC platform
7	phone	String		Yes	The phone number of the individual to be vetted against the phone number of the validation ID holder on the KYC platform

Endpoint

{{baseurl}}/api/v1/request/verification

Headers:

HTTP Method: POST

        Content-Type: application/json

        Authorization: Bearer access token

Request: {     “firstname”: “john”,     “lastname”: “doe”,     “birthDate”: “1990-01-01”,     “gender”: “male”,     “phone”: “08030000000”,     “validationType”: “BVN”,     “validationId”: “11111111111” }

Response :{     “responseCode”: “00”,     “responseMessage”: Successful,       “data”: { “type”: “BVN”,               “status”: “VERIFIED”,               “identityNumber”: “11111111111”,               “lastName”: “Doe”,               “firstName”: “John”,               “birthDate”: “1990-01-01”,               “reference”: “ISW|KYC|BVN|20200714|WFWVVCSBI”      } }

4.5Validate the BVN and Account Number individual

Description:  Given a specific validation request as detailed in table below, confirm that the individual with the account number and bvn specified exists. The system returns a YES in the data section of the response if the individual exists and is linked to the provided bvn. Otherwise, a NO is returned in the data section of the response.

#	Field Name	Data Type	Max Length / Format	Required	Description
1	firstname	String		Yes	The firstName of the individual to be vetted against the BVN and bank account details
2	lastname	String		Yes	The lastName of the individual to be vetted against the BVN and bank account details
3	birthDate	Date	yyyy-MM-dd	Yes	The date of birth of the individual to be vetted against the BVN and bank account details
4	gender	String		Yes	The gender of the individual to be vetted against the BVN and bank account details
5	phone	String		Yes	The phone number of the individual to be vetted against the BVN and bank account details
6	bvn	String	11	Yes	The BVN of the individual to be vetted
7	accountNumber	String		Yes	The account number of the individual whose details is to be vetted against the provided details
8	bankCode	String		Yes	The CBN approved unique bankCcode for the bank the account is in
9	country	String		Yes	The unique shortCode for the country the individuals bank is in

Endpoint

{{baseurl}}/api/v1/request/verification/bvn/account

Headers: 

HTTP Method: POST

Content-Type: application/json

Authorization: Bearer access token

Request:  { “firstname”: “john”,     “lastname”: “doe”,     “birthDate”: “1990-01-01”,     “gender”: “male”,     “phone”: “08030000000”,     “bvn”: “11111111111”,     “accountNumber”: “0696363603”,     “bankCode”: “044”,     “country”: “NGA” }

Response :{     “responseCode”: “00”,     “responseMessage”: Successful,     “data”: {   “type”: “BVN and Bank Account verification”,           “isVerified”: “NO”     } }