Bill Payment APIs

  • Home
  • Bill Payment APIs

Introduction

UfitPay Bill Payment API is designed for developers to easily integrate bill payment functionality on any application using any software programing technology or development platform

Our API attempts to conform to the RESTful design principles. You interact with the resources exposed through the API by accessing resource collection and element URIs using the HTTP POST or GET.

Access to our Bill Payment API is Freely available to all registered UfitPay customers and agents (Ufitpay wallet accounts). 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 Wallet API credentials

In order to interact with UfitPay Bill payment APIs, you need to enable API access on your account. To do this, go to Account Settings on the UfitPay Mobile App then click the Generate API Keys link. We will generate and send new API credentials to your registered email address;

Once generated, you will be able to retrieve your API credentials at any time by the View API keys link.

For added security, we recommend you restrict access to your API credentials to only white-listed IP addresses. You can do this by clicking the Restrict API Access link under Account Settings on UfitPay Mobile App.

Authentication

All requests to UfitPay API require authentication. Our API Authentication is implemented as 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 wallet API key
Api-Token: Your wallet 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 Wallet API Key: TSVLWCB5TO5RfJFCNkwSX8z0F8ZwD91
Test Wallet API Token: TS66uEwtekJEcWiwzC1gDdiDzKcJFk1


Available APIs

List Service GET » /services

This API allows you to fetch a list of all available UfitPay payment services. This endpoint is accessed by making an HTTP GET request to https://api.ufitpay.com/v1/services

Request Body Parameters
This endpoint has no body parameters

Sample success response (json)
{ "resource": "services", "status":"success", "data": [{ "service_id": "0001", "service_name": "Buy Airtime", "service_type": "airtime" }, { "service_id": "0002", "service_name": "Buy Data", "service_type": "data" }] }

Response parameters
service_id (int) This is the unique ID of the service
service_name (string) This is the name of the service
service_type (string) This is a unique tag name for the service

List Vendors POST » /vendors

This API allows you to fetch a list of all available vendors for a given UfitPay service. This endpoint is accessed by making an HTTP GET request to https://api.ufitpay.com/v1/vendors

Request Body Parameters
service_id (int) (required) This is the ID of the UfitPay service you want to fetch available vendors for.

Sample success response (json)
{ "resource": "vendors", "status":"success", "data": [{ "vendor_id": "0010", "vendor_name": "DSTV" }, { "vendor_id": "0011", "vendor_name": "GoTV" }] }

Response parameters
vendor_id (int) This is the UfitPay vendor's unique ID
vendor_name (string) This is the UfitPay vendor's name

List Packages POST » /packages

This API allows you to fetch available packages for a given UfitPay vendor This endpoint is accessed by making an HTTP GET request to https://api.ufitpay.com/v1/packages

Request Body Parameters
vendor_id (int) (required) This is the ID of the UfitPay vendor you want to fetch available packages for.

Sample success response (json)
{ "resource": "packages", "status":"success", "data": [{ "package_id": "0083", "package_name": "DSTV Premium 0" }, { "package_id": "0082", "package_name": "DSTV Compact" }] }

Response parameters
package_id (string) This is the UfitPay unique ID for the package
package_name (string) This is the package name

List Available Vendors with Packages & Price POST » /price_list

This API allows you to fetch all available packages from all available vendors with your account specific price information for a given service. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/price_list

Request Body Parameters
service_id (string) (required) This is the ID of the service you wish to fetch price list for. Use the Service List API to get a list of supported service IDs

Sample success response (json)
{ "resource": "price_list", "status": "success", "data": [{ "vendor_id": "0007", "vendor_name": "Smile Data", "packages": [{ "package": "0043", "package_name": "3GB MidNite (7 Days)", "price": "1522", "Fee": "0" }, { "package": "0044", "package_name": "3GB Weekend ONLY (2 Days)", "price": "1522", "Fee": "0" }, { "package": "0045", "package_name": " 1GB FlexiDaily (1 Days)", "price": "298", "Fee": "0" }] }, { "vendor_id": "0031", "vendor_name": "N-Tel Data Bundle", "packages": [{ "package": "0135", "package_name": "Access Passes (30 Days)", "price": "995", "Fee": "0" }, { "package": "0136", "package_name": "Access Passes 2GB (30 Days)", "price": "995", "Fee": "0" }] }] }

Response parameters
package (string) This is the UfitPay package ID
package_name (string) This is the name of the package for the vendor
price (string) This is your account specific price for the package. Please note that this depends on your account type and discount level, may vary from one account to another.
Fee (string) This is the service fee of the package if applicable

Get Order Price POST » /get_price

This API allows you to get the total payable amount for a given order. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/get_price

Request Body Parameters
service_id (int) (required) This is the service ID for the bill category. Use the Service List API to get a list of supported service IDs
vendor_id (int) (required) This is the vendor ID for the biller. Use the Vendor List API to get a list of supported vendor IDs
package_id (int) (not required for airtime topup service) This is the biller's package ID. Use the Package List API to get a list of supported package IDs
amount (float or int) (not required for some services) This is the amount pay in Naira (₦). This parameter is not required for most package-based services such as Cable-TV, Data Subscription, etc.

Sample success response (json)
{ "resource": "get_price", "status":"success", "data":{ "price": "1000.00", "fee": "5.00", "total": "1005.00" } }

Response parameters
cost (string) This is the service price (in ₦)
fee (string) This is the service charge (in ₦) where applicable
total (string) This is the total amount you will be charged for the service (in ₦)

Validation Payer Account POST » /account_validate

This API allows you to verify a customer's account or payer identifier with the vendor. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/account_validate

Request Body Parameters
account_number (string) (required) This is vendor's customer account number to validate
vendor_id (string) (required) This is UfitPay unique ID of the vendor you want to validate the account information for

Sample success response (json)
{ "resource": "account_validate", "status":"success", "data":{ "customer_name": "John Doe", "account_number": "1234567890", "amount_due": "12000" } }

Response parameters
customer_name (string) This is the customer's account name returned by the vendor
account_number (string) This is the account number you validated
amount_due (string) This is the total amount the payer is expected to pay in Naira (where applicable)

Initiate Bill Payment POST » /pay

This API allows you to initiate bill payment or mobile topup . This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/pay

Request Body Parameters
service_id (int) (required) This is the service ID for the bill category you want to pay. Use the Service List API to get a list of supported service IDs
vendor_id (int) (required) This is the vendor ID for the bill you want to pay. Use the Vendor List API to get a list of supported vendor IDs
package_id (int) (not required for airtime topup service) This is the package ID for the bill you want to pay. Use the Package List API to get a list of supported package IDs
account_number (string) (required) This is the vendor's customer identifier, phone number, etc. Set this to 1 for WAEC and similar vendors that requires no customer information. We recommend you verify this value using the Account Validation API or Phone Number Operator Lookup as the case may be before making a payment
amount (float or int) (not required for some services) This is the amount you wish to pay in Naira (₦). This parameter is not required for most package-based services such as Cable-TV, Data Subscription, etc.
request_ref (string) (optional) This is Your Own Unique transaction reference. If supplied, this can also be used to query status of this transaction.

Sample success response (json)
{ "resource": "pay", "status":"success", "data":{ "payment_status": "completed", "reference": "AT7568HFKUSLPRN4B908B", "cost": "1000.00", "token": "", "serial": "" } }

Response parameters
payment_status (string) This is the current status of the payment. Possible values are pending, completed, canceled, refund, on-hold or processing
reference (string) This is the UfitPay payment reference for the payment
cost (string) This is the amount deducted from your UfitPay wallet for the payment (in ₦)
token (string) This is the vendor's generated token such as Meter Token. This will only have a value for supported services.
Notice: In the event where a token is expected but this parameter returned empty, please call the "Transaction Query API" after a few seconds to obtain the token
serial (string) This is the vendor's generated serial number where applicable. This will only have a value for supported services.
Notice: In the event where a serial is expected but this parameter returned empty, please call the "Transaction Query API" after a few seconds to obtain the serial

Transaction Status Query API POST » /transaction

This API allows you to fetch the current status of a payment using the payment reference. This endpoint is accessed by making an HTTP GET request to https://api.ufitpay.com/v1/transaction

Request Body Parameters
reference (string) (required) This is the UfitPay payment reference returned after a payment is done
request_ref (string) (optional) This is Your Own Unique transaction reference if supplied while initiating the transaction.

Sample success response (json)
{ "resource": "transaction", "status":"success", "data":{ "reference": "AT7568HFKUSLPRN4B908B", "status": "completed", "transaction_date": "2022-02-22 22:22:22", "session_id": "000836867234733", "token": "1134-8876-9282-1000-1111", "serial": "" } }

Response parameters
status (string) This is the current status of the payment. Possible values are pending, completed, canceled, refund, on-hold or processing
reference (string) This is the returned balance currency
transaction_date (string) This is the date and time of the transaction
session_id (string) This is the unique NIP Session ID for a bank transfer transaction, or service tracking ID from other transaction types.
token (string) This is the vendor's generated token such as Meter Token. This will only have a value for supported services.
serial (string) This is the vendor's generated serial number where applicable. This will only have a value for supported services.