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.
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.
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
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
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 |
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) |
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
| 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.
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
| 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": "2024-04-20 14:01:22"
}
}
| 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. |
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
| 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": "2024-04-20 14:01:22"
},
{
"reference": "Y8903756USLPRN4BHHFSD",
"status": "pending",
"customer_account_id": "68307583",
"description": "Airport Pickup",
"amount": "31000.00",
"datetime": "2024-04-19 10:51:22"
}
]
}
| 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. |
Copyright @2024 Ynet Technology Ltd. All Rights Reserved