Introduction

UfitPay Financial Data API is designed for developers and fintechs to easily access a user's financial information on any application using any software programing technology or development platform

Access to this API is available to all registered UfitPay merchants with financial data API access enabled. A UfitPay wallet must be connected to your merchant account for billing purposes. You will likely need access to a web developer or programmer (if you’re not one) to get the most use out of UfitPay API.

Obtaining Merchant/Vendor API credentials

In order to interact with our merchant APIs, you need to enable API access on your merchant/vendors dashboard. This is usually enabled by default. To do this, go to Vendors Settings from your UfitPay Vendors Dashboard then click the API Settings tab view your API credentials.

You can also generate new API keys by clicking the Generate New keys button.

Authentication

All requests to this API require HTTP Header Authentication over TLS (HTTPS).

To authenticate your request, you need to pass the following parameters as part of your HTTP request headers;

Api-Key: Your merchant API key
API-Token: Your merchant API token

Test API Credentials

The following API Credentials can be used for development and test purpose only. Transactions done using these credentials are not treated as live

Test Merchants/Vendor API Key: VENDWCB5TO5RfJFCNkwSX8z0F8ZwD91
Test Merchants/Vendor API Token: VENDuEwtekJEcWiwzC1gDdiDzKcJFk1

Available APIs

BVN Data Retrieval POST » /bvn_data

This API allows you to retrieve a user's KYC full information using Bank Verification Number (BVN). This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/bvn_data

Integration Workflow:

• When you call this endpoint, we will first check if the supplied BVN is valid.
• If valid, we will proceed to check if the BVN owner has already given concent for its data to be shared with you.
• If prior concent has been given, we will retun a success response containing the retrieved BVN data.
• If concent is yet to be given by the user, we will send an OTP to the email address and phone number linked to the BVN. We will then return a Concent Required success response containg a unique request tracking reference.
• You will are required obtain the OTP from the user, then call the "BVN Concent Request" API supplying request_tracking_reference along with the otp code obtained from the user to retrieve the user's BVN data.

Please note that this endpoint is not free. A ₦25 charge applies per successful API request.

Request Body Parameters
bvn (string)	(required) This is the user's bank verification number to lookup

Sample success response with BVN data (json)
The following response will be returned if the user has previously given concent for its BVN data to be shared with you;

{ "resource": "bvn_data", "status":"success", "data": { "verify_status":"success", "gender": "female", "lga_of_origin": "Nnewi North", "lga_of_residence": "AMAC", "marital_status": "married", "nin": "", "nationality": "Nigeria", "state_of_origin": "Anambra State", "state_of_residence": "FCT", "title": "Mr", "first_name": "JOHN", "middle_name": "", "last_name": "DOE", "registration_date": "13-12-2021", "phone": "08077665522", "date_of_birth": "17-07-1987", "address": "Ijebu ode. Ondo State, nigeria" } }

Sample Concent Required success response (json)
The following response will be returned if the user's concent is required;

{ "resource": "bvn_data", "status":"success", "data": { "verify_status":"concent_required", "request_tracking_reference": "hsi873vdpovgc-37ev-shv8d292" } }

BVN Concent Request POST » /bvn_concent

This API allows you to request a user's concent to access the user's KYC full information using Bank Verification Number (BVN). This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/bvn_concent

Please note that this endpoint is not free. A ₦25 charge applies per successful API request.

Request Body Parameters
bvn (string)	(required) This is the user's bank verification number you are getting concent for
request_tracking_reference (string)	(required) This is the unique request_tracking_reference we returned with the Concent Required response
otp (string)	(required) This is the OTP code you collected from the user for concent cerification

Sample success response with BVN data (json)
The following response will be returned if the OTP supplied matched the one we sent to the User;

{ "resource": "bvn_concent", "status":"success", "data": { "verify_status":"success", "gender": "female", "lga_of_origin": "Nnewi North", "lga_of_residence": "AMAC", "marital_status": "married", "nin": "", "nationality": "Nigeria", "state_of_origin": "Anambra State", "state_of_residence": "FCT", "title": "Mr", "first_name": "JOHN", "middle_name": "", "last_name": "DOE", "registration_date": "13-12-2021", "phone": "08077665522", "date_of_birth": "17-07-1987", "address": "Ijebu ode. Ondo State, nigeria" } }

Linked Bank Account List POST » /linked_accounts

This API allows you to retrieve a list of all bank accounts operated by a user using Bank Verification Number (BVN). This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/linked_accounts

Please note that this endpoint is not free. A ₦100 charge applies per successful API request.

Request Body Parameters
bvn (string)	(required) This is the user's bank verification number to lookup

Sample success response (json)
{ "resource": "bvn_data", "status":"success", "data": [{ "bank_name":"Zenith Bank", "bank_code": "057", "account_number": "1100998877", }, { "bank_name":"Fidelity Bank", "bank_code": "123", "account_number": "0927926862", }] }

Bank Account Balance Inline Integration » accountbalance

This API allows you to securly authenticate and retrieve a user's bank account balance in real-time. This endpoint is currently only available under UfitPay Inline Integration

Please note that this endpoint is not free. A ₦60 charge applies per successful request.

Consolidated Financial Data Inline Integration » financialdata

This API allows you to securly authenticate and retrieve a user's consolidated financial data and analytic in real-time including incomes, expense, salary, loans, etc. This endpoint is currently only available under UfitPay Inline Integration

Please note that this endpoint is not free. A ₦170 charge applies per successful request.

>Bank Statement Inline Integration » bankstatement

This API allows you to securly authenticate and retrieve a user's bank account statement for a given period in real-time. This endpoint is currently only available under UfitPay Inline Integration

Please note that this endpoint is not free. A ₦160 charge applies per successful request.

Updated Financial Data Retrieval POST » fin_data_refresh

This API allows you to retrieve most recent version of financial data a previoously authenticated bank account. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/fin_data_refresh

Please note that this endpoint is not free. Applicable fee depends on the value passed under the "type" parameter.

Request Body Parameters
type (string)	(required) This is the the financial data resource you want to retrieve. Supported values are "financialdata" for Consolidated Financial Data retrieval, "accountbalance" for bank balance retrieval or "bankstatement" for Bank Statement retrieval
account_id (string)	(required) This is the value returned under data.account_id the first time the user authenticated its bank account via UfitPay Inline Integration
callback_url (string)	(required) This is the URL you would like the retrieved data sent to once processed by the user's bank

Response and Webhook
Upon successful retrieval of requested financial data, we will return exactly same response as with the respective requests when initiated via UfitPay Inline Integration. We will also send thesame data via HTTP POST to any callback URL you specified with your API call.