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

Nigeria: https://ng-credit.apitd.net/credit/data/creditreport/v1

API

Request Methods	Content-Type	Output Format	Character Set
POST	application/json	Json	UTF-8

Authentication

Parameter	Type	Required/Optional	Notes
partner_code	String	Required	To be assigned by TD
partner_key	String	Required	To be assigned by TD

Request Parameter

Parameter	Type	Required/Optional	Notes
id_number	String	Required	ID number, bank verification number for Nigeria
id_type	String	Required	ID type, "bvn" for Nigeria
country	String	Required	ISO 3166 country code: "NG" for Nigeria
phone_number	String	Required	phone number without country code
name	String	Required	name
ext	Object	Optional	custom 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

Parameter	Type	Description	Notes
code	Integer	API status code
message	String	Status information	The specific cause of the exception is displayed when the API is in an abnormal state
sequence_id	String	Response unique code	A unique identifier used to track the record of each request

API Status Code

code	Message	Description
200		Success
300	Service not purchased or not effective	Service not purchased or not effective
301	Service not purchased	Service not purchased
302	Service has been suspend	Service has been suspend
303	Not enough balance	Not enough balance
304	Service expired	Service expired
9500	Internal error	Internal 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

URL	HTTP Method	Request Content Type	Response Content Type	Charset
api-base-url?partner_code=xxx×tamp=xxx&access_key=xxx&sign=xxx	POST	application/json	JSON	UTF-8

Authentication

Parameter	Type	Description	Required/Optional	Notes
partner_code	String	Partner Code	Required	Assigned by TD
timestamp	String	Current timestamp	Required	Millisecond level
access_key	String	Access key	Required	Assigned by TD
sign	String	Sign	Required

Sign generation method

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

access_secret is assigned by TD

Headers

Parameter name	Value	Required/Optional
Content-Type	application/json	Required

Response Parameters For Push Notifications

Parameter	Type	Description
result	String	If 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.
code	Integer	API status code
message	String	Status Information
sequence_id	String	Unique identifier used to track each request record
data	Object	Report details. Only displayed when the result is hit
ext	Object	custom content, the same as request Parameter in Asynchronous Query API. Only displayed when the parameters are entered

Enumeration values of code and message

Code	Message	Description
200
9500	Service unavailable, please retry later	Service unavailable, please retry later

Parameters and Description of data

Part of Report	Parameter	Description
report_detail_bvn	cir_number	Credit report unique number
	report_order_date	Date of the report request
	institution_name	Name of the institution granting the facility
	bvn_number	Bank Verification Number (BVN)
	search_confidence_score	Score for searching topics
inquiry_product	bank	Bank
	micro	Microcredit banks
	mortgage	Mortgage bank
	nbfc	Non-bank financial company
	other	Other
	total	Total
	product_type	Product categories
classification_prod_type	currency	Currency
	no_acc_last_six_mon	The total number of facilities for this product type in the past six months
	no_of_accounts	The total number of facilities for this product type in the past 24 months
	recent_overdue_date	The most recent overdue date on the facility
	product_type	Product categories
	sanctioned_amount	Total amount approved for facilities
	total_outstanding_balance	Total outstanding balance for facility type
	amount_overdue	Loan overdue amount
inquiry_history_details	facility_type	Type of facility
	inquiry_date	Date of searching topic
	institution_type	Type of institution
	sno	Number
classification_ins_type	currency	Currency
	institution_type	Type of institution
	no_of_accounts	Total number of facilities
	oustanding_balance	Total outstanding balance of grouping institutions
	approved_credit_sanctioned	Total amount approved for facilities
	amount_overdue	Loan overdue amount
conscomm_details - conscomm_details_id	identifier_number	ID document type number
	id_type	ID document type (BVN, passport, driver's license)
conscomm_details - conscomm_details_subject	address	Address
	application_viability_score	Application Feasibility Score
	date_of_birth	birthday(DD-Mon-YYYY)
	date_of_birth_m	birthday(YYYY-MM-DD)
	gender	Gender
	name	Name
	nationality	Nationality
	phone_no1	Mobile 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

Parameter	Type	Description	Required/Optional	Notes
code	Integer	API status code	Required
message	String	Status message	Required	In the API exception state, the specific exception reason will be output.

API Status Code

code	**Description**
200	Success

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

Nigeria: https://ng-credit.apitd.net/credit/data/creditreport/query/v1

API

Request Methods	Content-Type	Output Format	Character Set
POST	application/json	Json	UTF-8

Authentication

Parameter	Type	Required/Optional	Notes
partner_code	String	Required	To be assigned by TD
partner_key	String	Required	To be assigned by TD

Request Parameter

Parameter	Type	Required/Optional	Notes
sequence_id	String	Required	sequence_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

code	Message	Description
200		Success
9060	{parameter} empty	{parameter} empty
9080	Only queries within 48 hours are available.	Only queries within 24 hours are available
9083	There was an error occurred, please try again	There was an error occurred, please try again
9084	Work in progress	Report is progress, please retry later
9500	Internal error	Service 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"
}