Nigeria Credit Report

Credit Report including personal basic information and credit information in Nigeria. This is an asynchronous interface, returning report details to customers.

STEP 1:Asynchronous Query

API Method

Base URL

API

Request MethodsContent-TypeOutput FormatCharacter Set
POSTapplication/jsonJsonUTF-8

Authentication

ParameterTypeRequired/OptionalNotes
partner_codeStringRequiredTo be assigned by TD
partner_keyStringRequiredTo be assigned by TD

Request Parameter

ParameterTypeRequired/OptionalNotes
id_numberStringRequiredID number, bank verification number for Nigeria
id_typeStringRequiredID type, "bvn" for Nigeria
countryStringRequiredISO 3166 country code: "NG" for Nigeria
phone_numberStringRequiredphone number without country code
nameStringRequiredname
extObjectOptionalcustom content, no more than 1KB

Request Example For Push Notifications

{
	"id_number": "22370756505",
	"id_type": "bvn",
	"country": "NG",
	"phone_number": "9981234567",
	"name": "Amlodd Adisa"
}

Response Parameter

ParameterTypeDescriptionNotes
codeIntegerAPI status code
messageStringStatus informationThe specific cause of the exception is displayed when the API is in an abnormal state
sequence_idStringResponse unique codeA unique identifier used to track the record of each request

API Status Code

codeMessageDescription
200Success
300Service not purchased or not effectiveService not purchased or not effective
301Service not purchasedService not purchased
302Service has been suspendService has been suspend
303Not enough balanceNot enough balance
304Service expiredService expired
9500Internal errorInternal error
9060{parameter} empty{parameter} empty
9061{parameter} error{parameter} error

After post the data to TD through the above API interface, TD will return the credit report to you through the bellowing API.


STEP 2:Webhook Configuration

API Format

Base URL

The subscription API address you provide to TD. Please contact us for the configuration and we will help you with it.

Remark: The subscription API address supports http with port 80 and https with port 443.

API

URLHTTP MethodRequest Content TypeResponse Content TypeCharset
api-base-url?partner_code=xxx×tamp=xxx&access_key=xxx&sign=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
timestampStringCurrent timestampRequiredMillisecond level
access_keyStringAccess keyRequiredAssigned by TD
signStringSignRequired

Sign generation method

sign = HmacSHA1(partner_code+timestamp+access_key,access_secret)

access_secret is assigned by TD

Headers

Parameter nameValueRequired/Optional
Content-Typeapplication/jsonRequired

Response Parameters For Push Notifications

ParameterTypeDescription
resultStringIf the report is successfully obtained, "hit" is returned
If there is no report for the given person, "no_record" is returned
If other conditions occur, "error" is returned.
codeIntegerAPI status code
messageStringStatus Information
sequence_idStringUnique identifier used to track each request record
dataObjectReport details. Only displayed when the result is hit
extObjectcustom content, the same as request Parameter in Asynchronous Query API. Only displayed when the parameters are entered
Enumeration values of code and message
CodeMessageDescription
200
9500Service unavailable, please retry laterService unavailable, please retry later
Parameters and Description of data
Part of ReportParameterDescription
report_detail_bvncir_numberCredit report unique number
report_order_dateDate of the report request
institution_nameName of the institution granting the facility
bvn_numberBank Verification Number (BVN)
search_confidence_scoreScore for searching topics
inquiry_productbankBank
microMicrocredit banks
mortgageMortgage bank
nbfcNon-bank financial company
otherOther
totalTotal
product_typeProduct categories
classification_prod_typecurrencyCurrency
no_acc_last_six_monThe total number of facilities for this product type in the past six months
no_of_accountsThe total number of facilities for this product type in the past 24 months
recent_overdue_dateThe most recent overdue date on the facility
product_typeProduct categories
sanctioned_amountTotal amount approved for facilities
total_outstanding_balanceTotal outstanding balance for facility type
amount_overdueLoan overdue amount
inquiry_history_detailsfacility_typeType of facility
inquiry_dateDate of searching topic
institution_typeType of institution
snoNumber
classification_ins_typecurrencyCurrency
institution_typeType of institution
no_of_accountsTotal number of facilities
oustanding_balanceTotal outstanding balance of grouping institutions
approved_credit_sanctionedTotal amount approved for facilities
amount_overdueLoan overdue amount
conscomm_details - conscomm_details_ididentifier_numberID document type number
id_typeID document type (BVN, passport, driver's license)
conscomm_details - conscomm_details_subjectaddressAddress
application_viability_scoreApplication Feasibility Score
date_of_birthbirthday(DD-Mon-YYYY)
date_of_birth_mbirthday(YYYY-MM-DD)
genderGender
nameName
nationalityNationality
phone_no1Mobile number 1

Response Example

Hit situation

{
	"sequence_id": "1699272744735016i303341798930550",
	"code": 200,
	"message": "success",
	"result": "hit",
	"data": {
		"report_detail_bvn": {
			"report_order_date": "24-aug-2023",
			"search_confidence_score": "100%",
			"cir_number": "w-0087662519/2023",
			"institution_name": "finnew fintech limited",
			"bvn_number": 22366507571
		},
		"inquiry_product": [{
			"other": "0",
			"total": "6",
			"product_type": "asset acquisition loan",
			"bank": "0",
			"nbfc": "0",
			"mortgage": "0",
			"micro": "6"
		},
		{
			"other": "1",
			"total": "5",
			"product_type": "overdraft",
			"bank": "0",
			"nbfc": "0",
			"mortgage": "0",
			"micro": "4"
		},
		{
			"other": "1",
			"total": "11",
			"product_type": "total",
			"bank": "0",
			"nbfc": "0",
			"mortgage": "0",
			"micro": "10"
		}],
		"classification_prod_type": [{
			"currency": "ngn",
			"product_type": "term loan",
			"recent_overdue_date": "31-jul-2023",
			"no_acc_last_six_mon": "1",
			"amount_overdue": "139,691",
			"sanctioned_amount": "155,000",
			"no_of_accounts": "5",
			"total_outstanding_balance": "139,691"
		}],
		"inquiry_history_details": [{
			"institution_type": "micro lenders",
			"sno": "1",
			"facility_type": "overdraft",
			"inquiry_date": "18-may-2023"
		},
		{
			"institution_type": "other organizations",
			"sno": "2",
			"facility_type": "overdraft",
			"inquiry_date": "17-may-2023"
		},
		{
			"institution_type": "micro lenders",
			"sno": "3",
			"facility_type": "overdraft",
			"inquiry_date": "13-may-2023"
		},
		{
			"institution_type": "micro lenders",
			"sno": "4",
			"facility_type": "overdraft",
			"inquiry_date": "04-may-2023"
		},
		{
			"institution_type": "micro lenders",
			"sno": "5",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "07-mar-2023"
		},
		{
			"institution_type": "micro lenders",
			"sno": "6",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "13-feb-2023"
		},
		{
			"institution_type": "micro lenders",
			"sno": "7",
			"facility_type": "overdraft",
			"inquiry_date": "06-feb-2023"
		},
		{
			"institution_type": "micro lenders",
			"sno": "8",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "15-oct-2022"
		},
		{
			"institution_type": "micro lenders",
			"sno": "9",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "28-sep-2022"
		},
		{
			"institution_type": "micro lenders",
			"sno": "10",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "17-sep-2022"
		},
		{
			"institution_type": "micro lenders",
			"sno": "11",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "17-sep-2022"
		},
		{
			"institution_type": "micro lenders",
			"sno": "12",
			"facility_type": "asset acquisition loan",
			"inquiry_date": "26-jan-2022"
		}],
		"classification_ins_type": [{
			"currency": "ngn",
			"institution_type": "micro lenders",
			"amount_overdue": "139,691",
			"oustanding_balance": "139,691",
			"approved_credit_sanctioned": "155,000",
			"no_of_accounts": "5"
		}],
		"conscomm_details": {
			"conscomm_details_id": [{
				"identifier_number": "22366507571",
				"id_type": "bank verification number"
			}],
			"conscomm_details_subject": {
				"nationality": "nigeria",
				"application_viability_score": "na",
				"address": "not available 025 ng lagos nigeria ",
				"date_of_birth_m": "1999-06-05",
				"gender": "male",
				"phone_no1": "9026061222",
				"date_of_birth": "05-jun-1999",
				"name": "okechukwu uzodinma akubueze"
			}
		}
	}
}

No_record situation

{
	"sequence_id": "1699272744735016i303341798930550",
	"code": 200,
	"message": "success",
	"result": "no_record"
}

Response Parameters

Parameters that your business system needs to respond to after receiving a push request

ParameterTypeDescriptionRequired/OptionalNotes
codeIntegerAPI status codeRequired
messageStringStatus messageRequiredIn the API exception state, the specific exception reason will be output.

API Status Code

code**Description**
200Success

Response Example

{
  "code": 200,
  "message": ""
}

Note: If the status code you return is not 200, we will retry 3 times. If we failed for all 3 times, we will not push the data any more. However, you can query through the following query interface if the push is missed.


Backup Synchronous Query: ONLY use when webhook failed

If you have not received the returned data push for a long time, you can pass the sequence_id returned by the first call through the following query interface to query the results. This interface only supports result query within 24 hours).

Remark: This interface is back up interface for asynchronous queries. After configuring the asynchronous interface, if the call is successful but there is no return, you can query through this interface

API Method

Base URL

API

Request MethodsContent-TypeOutput FormatCharacter Set
POSTapplication/jsonJsonUTF-8

Authentication

ParameterTypeRequired/OptionalNotes
partner_codeStringRequiredTo be assigned by TD
partner_keyStringRequiredTo be assigned by TD

Request Parameter

ParameterTypeRequired/OptionalNotes
sequence_idStringRequiredsequence_id from the first step

Response Parameters

The response will be the same with the above push request parameters. Please refer to Response Example within this document.

API Status Code

codeMessageDescription
200Success
9060{parameter} empty{parameter} empty
9080Only queries within 48 hours are available.Only queries within 24 hours are available
9083There was an error occurred, please try againThere was an error occurred, please try again
9084Work in progressReport is progress, please retry later
9500Internal errorService is temporarily unavailable, please retry later

Response Example(Success)

The response will be the same with the above push request parameters. Please refer to Response Parameters For Push Notifications within this document.

Response Example(ERROR)

{
    "code": 9080,
    "message": "Only queries within 48 hours are available.",
    "sequence_id": "1703123181798646G109E3248****377"
}