Virtual Account API - UfitPay.com

Introduction

UfitPay Virtual Banking API is designed for developers to easily automated banking and virtual account number features on any application using any software programing technology or development platform

Access to this API is available to all registered UfitPay merchants with virtual banking service access granted. 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 virtual banking 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

Integration Work-Flow

Below is a typical implementation of UfitPay virtual account number API for a wallet-based system;

Step 1: Create a new column "virtual_account_num" on your customers database to hold the customer's dedicated virtual bank account number
Step 2: Call the "Create Virtual Account Number" API using the customer's name and BVN to generate a unique virtual account for the customer
Step 3: Update the returned account number against the virtual_account_num database column on the customer's record
Step 4: Create a callback script to capture and handle UfitPay payment notifications on your server
Step 5: Call the "Merchant Payment Query" API to validate the received callback using the transaction_reference
Step 6: If the callback request includes the "credit_account_number" parameter, use the value of this parameter to find the owner of the inflow by searching your customers database against virtual_account_num column
Step 7: Credit the matched customer's wallet with the received amount

Available APIs

Create Virtual Account Number POST » /create_bank_account

This API allows vendors to issue a full-featured virtual NUBAN account number to a customer. This endpoint is only available to Ufitpay Vendors and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/create_bank_account

Request Body Parameters
bank (string)	(required) Set which bank the accoint will be domicile in. Supported values are SafeHaven and GTBank. Please note that this value is case-sensitive!
bvn (string)	(required) This is the Bank Verification Number (BVN) to be associated with the virtual bank account.
nin (string)	(required for GTBank) This is the National Identification Number (NIN) to be associated with the virtual bank account. This is a new CBN requirements.
first_name (string)	(required) This is the account holder's first name. This must match the first name on the supplied BVN
last_name (string)	(required) This is the account holder's last name. This must match the last name on the supplied BVN.
business_name (string)	(optional) Set this to a valid Government Approved business name to create a business bank account.

Sample success response (json)
{ "resource": "create_bank_account", "status":"success", "data":{ "reference": "12345678", "account_number": "7590000000", "account_name": "John Doe", "bank_name": "GTBank", "bank": "035", "currency": "NGN" } }

Response parameters
bank_name (string)	This is the bank the generated account is domicile in
reference (string)	This is the unique reference for the generated account number.
account_number (string)	This is the generated 10-digit NUBAN account number.
account_name (string)	This is the assigned account name for the generated bank account
bank (string)	This is the bank institution code for the generated account.
currency (string)	This is the currency of the generated bank account

Once created, this account number can be used to receive payment from any bank in Nigeria. We will always send details of the every payment received into any of your virtual accounts in real-time via (Form Encoded) HTTP POST to your callback URL (If provided during setup). It is important to verify this data using the verify_payment end-point before giving value.

Refer to Merchant Payment Notification Webhook for details of what we send to your callback URL.

Query Merchants Virtual Bank Account Statement POST » /search_vendor_bank_statement

This API allows merchants to search a UfitPay virtual bank accounts for deposits/payments received. This endpoint is only available to Ufitpay merchants and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/search_vendor_bank_statement

Request Body Parameters
destination_account (string)	(required) This is the virtual account number to quesry statement for.
source_accountnumber (string)	(optional) This is the payer or originating account number to search for
originator_name (string)	(optional) This is the originating account name, depositor's name or payment narration to search for
amount (int)	(optional) This is the expected payment amount (in naira) to search for
datetime (string)	(optional) This is the payment date to search for (YYYY-MM-DD. eg 2024-10-08)

Note: If more than one of the four parameters above are supplied, only records that matched the supplied parameters will be returned. If none of the four parameters is supplied, all payment records will be returned

Sample success response (json)
{ "resource": "search_vendor_bank_statement", "status":"success", "records":"1", "data":[{ "amount": "2600", "paymentreference": "5725692722", "destination_account": "9876543210", "source_accountnumber": "0123456789", "source_bankname": "FIRST BANK OF NIGERIA", "credit_sessionid": "1234567889906", "depositor_name": "JOHN DOE", "datetime": "2024-10-08 09:09:03" } ] }

Response parameters
destination_account (string)	This is the virtual account the payment was received into
datetime (string)	This is the actual date and time the payment was received (YYYY-MM-DD HH:MM:SS)
credit_sessionid (string)	This is the unique bank credit session ID
paymentreference (string)	This is the unique credit reference from the originating bank
source_accountnumber (string)	This is the NUBAN bank account number originated the payment
source_bankname (string)	This is the name of the bank that originated the payment
depositor_name (string)	This is the depositor's name or originating bank account name
amount (string)	This is the actual transaction amount paid.

List Virtual Accounts POST » /list_bank_accounts

This API allows vendors to fetch a list of all virtual bank account under their profile (excluding disposable accounts). This endpoint is only available to Ufitpay Vendors and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/list_bank_accounts

Request Body Parameters
filter (string)	(optional) This is a search phrase to use in filtering returned results

Sample success response (json)
{ "resource": "list_bank_accounts", "status":"success", "data":[{ "reference": "123456", "account_name": "John Doe", "account_number": "0123456789", "bank_name": "WEMA", "bvn": "1234567889906" }, { "reference": "567890", "account_name": "Jane Ogu", "account_number": "0123456789", "bank_name": "Providus", "bvn": "1234567889906" } ] }

Update Virtual Account Information POST » /update_bank_accoun_name

This API allows vendors to update KYC information on a virtual bank account under their profile. This endpoint is only available to Ufitpay Vendors and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/update_bank_accoun_name

Request Body Parameters
account_number (string)	(required) This is the virtual account number to be updated.
bvn (string)	(required) This is the Bank Verification Number (BVN) to be associated with the new KYC information.
first_name (string)	(required) This is the new account holder's first name. This must match the first name on the supplied BVN
last_name (string)	(required) This is the new account holder's last name. This must match the last name on the supplied BVN.
business_name (string)	(optional) Set this to a valid Government Approved business name for a business account KYC.

Sample success response (json)
{ "resource": "update_bank_accoun_name", "status":"success", "data":["account_number": "7590000000", "account_name": "John Doe", "bank_name": "Providus", "currency": "NGN" ] }

Delete Virtual Account POST » /delete_bank_account

This API allows vendors to delete a virtual bank account under their profile. This endpoint is only available to Ufitpay Vendors and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/delete_bank_account

Request Body Parameters
account_number (string)	(required) This is the virtual account number to be deleted

Sample success response (json)
{ "resource": "delete_bank_account", "status":"success", "data":[] }

Generate Disposable Account Number POST » /create_disposable_bank_account

This API allows vendors to generate a temporally virtual account number for a customer. This endpoint is only available to Ufitpay Vendors/merchants and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/create_disposable_bank_account

NOTE! Virtual accounts created with this endpoint has a maximum validity of 1 hour. The account may be deleted or assigned to a different user at the end of the validity period. It is very important to inform your customers about this as payments made into such accounts outside the validity period may be difficult to recover or reconciled.

Request Body Parameters
bank (string)	(required) Set which bank the accoint will be domicile in. Supported values are GTBank, WEMA or SafeHaven. Please note that this value is case-sensitive!
first_name (string)	(required) This is the account holder's first name. This must match the first name on the supplied BVN
last_name (string)	(required) This is the account holder's last name. This must match the last name on the supplied BVN.
business_name (string)	(optional) Set this to a valid Government Approved business name to create a business bank account.
bvn (string)	(optional) This is the Bank Verification Number (BVN) to be associated with the virtual bank account. The vendor's profiled BVN is used If not supploed.
validity (int)	(optional) This is the duration in minutes to retain the virtual bank account. The value must be between 5 and 60. Default value is 60 (1 hour)
request_ref (string)	(optional) This is Your Own Unique payment tracking reference. If supplied, this can also be used to query for deposit using the verify_payment endpoint.
callback_url (string)	(optional) This is a custom URL you would like notifications sent to for all payments received with this account. If supplied, this URL will be used instead of the one defined on your merchant API settings.

Response parameters
reference (string)	This is the unique reference for the generated account number.
account_number (string)	This is the generated 10-digit NUBAN account number.
account_name (string)	This is the assigned account name for the generated bank account
expire (string)	This is the date and time the generated bank account will be disposed. (The time zone is +1 WAT)
bank_name (string)	This is the bank the generated account is domicile in
currency (string)	This is the currency of the generated bank account

Once created, this account number can be used to receive payment from any bank in Nigeria while it is still valid. During the validity period, we will send details of the every payment received into the generated accounts in real-time via (Form Encoded) HTTP POST to your callback URL (If provided during setup). It is important to verify this data using the verify_payment end-point before giving value.