Merchant Payment APIs

  • Home
  • Merchant Payment APIs

Introduction

UfitPay Merchant API is designed for developers to easily automated various collection functionalities 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 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

Vendor Payer Validation Webhook GET » http://your-callback-url?validateUserAccount={payer-identity}

If supplied during your onboarding, UfitPay will send a HTTP GET request to your webhook URL containing the exact data the payer provided on UfitPay as payer identifier.

This data will be passed to your URL using HTTP REQUEST parameter name validateUserAccount.

For example, if a payer enters 1234556 as the payer identifier while initiating a payment to you, and your Payer Validation API URL is https://abcd.com, UfitPay will send a request to https://abcd.com?validateUserAccount=123456.
Your server is expected to respond in the following format;

Sample expected successful validation response (json)
{ "status": "success", "message":"OK", "name":"Your Customer Name", "amount_due":"21000" }

Sample expected failed validation response (json)
{ "status": "error", "message":"Your error message", "name":NULL, "amount_due":"0" }

Parameter descriptions
status (string) This tells our server whether or now the customer/payer's information was successfully validated. Expected value for any successful validation is "status"
message (string) This is your error message to be shown to the payer in the case of unsuccessful validation.
name (string) This is the validated account name to be shown to the payer.
amount_due (string) This is the amount the payer is expected to pay (if applicable). Setting any value greter than zero will override any amount inputed by the payer

Vendor's Payment Notification Webhook POST » http://your-callback-url

For every successful payment for a vendor's service, UfitPay will send a (Form Encoded) HTTP POST containing details of the payment to the vendor's callback URL (If provided during setup or passed via callback_url with the API call). It is important to verify this data using the verify_payment end-point before giving value.

POSTed parameters
transaction_date (string) This is the actual date and time the payment was made (YYYY-MM-DD HH:MM:SS)
customer_account_id (string) This is the unique customer / payer identifier supplied by the customer during the payment on Ufitpay. This could be your Invoice number, customer ID, etc
description (string) This is a description of the payment
customer_email (string) This is the contact email address supplied by the payer during the payment
customer_name (string) This is the name of the entity or UfitPay user that made the payment
transaction_value (string) This is the amount paid.
transaction_fee (string) This is the transaction charges if applicable to the transaction.
transaction_reference (string) This is the transaction reference for the payment
service_code (string) This is the unique UfitPay service ID for the puchased vendor service
session_id (string) This is the unique NIP Session ID (for bank credit transactions) or Biller's ID for other services
credit_account_number (string) This is the virtual bank account number that received the payment. This is only available for virtual account credit transactions
request_ref (string) This is your own unique reference for a Pay-with-Ufitpay transaction (if supplied)

Payment Link Creation API POST » /get_payment_link

This API allows Merchants to generate a UfitPay payment link for a service. This endpoint is only available to Ufitpay Merchants and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/get_payment_link

Request Body Parameters
vendor_id (string) (required) This is your unique UfitPay merchant/vendor ID. Usually the same as vendor login username
customer_account_id (string) (required) This is the unique customer / payer identifier for the service.
service_code (string) (required) This is your assigned Service Code for the service. You can find this under My Services on your Vendors Dashboard
payer_email (string) (required) This is the Payer's contact email address.
amount (string) (required) This is the amount to be paid in Naira. You can set this to zero if the service has a pre-defined amount on UfitPay.
request_ref (string) (optional) This is Your Own Unique payment tracking reference. If supplied, this can also be used to validate status of the payment using the verify_payment endpoint.
callback_url (string) (optional) This is a custom URL you would like payment notification sent to for this transaction. If supplied, this URL will be used instead of the one defined on your merchant API settings.
return_url (string) (optional) This is the URL you want the payer returned to when the payment is completed or canceled.

Sample success response (json)
{ "resource": "get_payment_link", "status":"success", "data":{ "request_ref": "abcdxyz", "link": "https://bit.ly763gdh3", "currency": "NGN" } }

Response parameters
request_ref (string) This is the same Unique transaction tracking reference you supplied with your request under request_ref parameter.
link (string) This is the generated UfitPay payment link/URL to be given to the payer
currency (string) This is the currency that will be used for the payment on UfitPay

You can redirect the payer to the URL returned under the "link" parameter to complete payment on UfitPay.

Once the payer completes payment on UfitPay, we will redirect the payer to the URL you supplied under return_url parameter. We will also forward details of the payment 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 Vendor's Payment Notification Webhook for details of what we send to your callback URL.

Merchants/Vendor's Payment Verification API POST » /verify_payment

This API allows vendors to verify status of a payment using the UfitPay payment reference. This endpoint is only available to Ufitpay Vendors and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/verify_payment

Request Body Parameters
transaction_reference (string) (required if request_ref is not supplied) This is your unique UfitPay payment reference for the payment
request_ref (string) (optional if transaction_reference is supplied) This is Your Own Unique transaction tracking reference if supplied while generating a payment link.

Sample success response (json)
{ "resource": "verify_payment", "status":"success", "data":{ "transaction_reference": "AT7568HFKUSLPRN4B908B", "status": "completed", "customer_account_id": "68307583", "description": "Hotel Reservation", "service_code": "invoice", "transaction_value": "52000.00", "transaction_date": "2022-10-04 14:34:21" } }

Response parameters
service_code (string) This is the unique UfitPay service ID for the puchased vendor service
transaction_date (string) This is the actual date and time the payment was made (YYYY-MM-DD HH:MM:SS)
customer_account_id (string) This is the unique customer / payer identifier supplied by the customer during the payment on Ufitpay. This could be your Invoice number, customer ID, etc
status (string) This is the current status of the payment. Possible values are pending, completed, canceled, refund, on-hold or processing
transaction_reference (string) This is the unique reference for the transaction/payment
description (string) This is a description of the payment
transaction_value (string) This is the actual amount paid.

Merchants/Vendor's Payment Search API POST » /search

This API allows vendors to search if a payment has been completed using the customer's account identifier. This endpoint is only available to Ufitpay Vendors and is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/search

Request Body Parameters
customer_account_id (string) (required) This is your unique customer / payer identifier on Ufitpay. This could be your Invoice number, customer ID, etc, but must match the identifier supplied by the customer during the payment
limit (int) (optional) This is the number or matched records you want returned, sorted by most recent records. The default value is 1 (which returns only the last payment from the customer)
completed_only (boolean) (optional) Setting this to "true" will return only completed payments, while "false" will return any matched payment status. The default value is "true"

Sample success response (json)
{ "resource": "search", "status":"success", "data":[{ "reference": "AT7568HFKUSLPRN4B908B", "status": "completed", "customer_account_id": "68307583", "description": "Hotel Reservation", "amount": "52000.00", "datetime": "2022-10-04 14:34:21" }, { "reference": "Y8903756USLPRN4BHHFSD", "status": "pending", "customer_account_id": "68307583", "description": "Airport Pickup", "amount": "31000.00", "datetime": "2022-10-03 11:24:21" } ] }

Response parameters
datetime (string) This is the actual date and time the payment was made (YYYY-MM-DD HH:MM:SS)
customer_account_id (string) This is the unique customer / payer identifier supplied by the customer during the payment on Ufitpay. This could be your Invoice number, customer ID, etc
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 unique reference for the transaction/payment
description (string) This is a description of the payment
amount (string) This is the actual transaction amount paid.