Introduction

UfitPay uses Webhooks to communicate updates on transaction other requests initiated with our API for you to implement additional workflows based on these events. Each time an event that you listen to occurs, we submits a POST request to the designated Webhook URL with information about the event.

Your callback endpoint is expected to respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your server must return a 2xx HTTP status code. This status code should only indicate receipt of the message, not an acknowledgement that it was successfully processed by your system. Any other information returned in the response headers or response body is ignored..

Setting-up Webhooks

In order to receive webhook events from UfitPay, you must either specify a webhook URL (for merchants) under the API settings page on your dashboard, or pass the webhook URL using the callback_url parameter durring your request to endpoints that supports webhook events. Please note that the URL passed using the callback_url parameter will always override your dashboard webhook settings.

Webhook Format

UfitPay sends webhook event data in either a JSON encoded HTTP POST or a Form-encoded HTTP POST. The format of the webhook data varies from one event to another. A more uniformed structure may apply in a future release.

Webhook Event Simulator

UfitPay webhook event simulator allows to test your webhook setup by sending dummy data to it. Simply enter your webhook URL then select event to trigger

Webhook Events

Merchant Payment Notification Webhook Form Encoded POST » http://your-callback-url

For every successful payment to merchant's business, 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)

Bank Account Balance Webhook JSON Encoded POST » http://your-callback-url

For every successful bank account balance retrieval, UfitPay will send a (JSON Encoded) HTTP POST containing details of the retrieved data.

Sample webhook payload(json)
{ "event":"accountbalance", "reference":"12345689abcdef", "account_id": "ahk387t4bd90383fev3eg973", "status":"retrieved", "account_bank_name":"Zenith Bank", "account_number":"0123456789", "account_name":"John Doe", "account_currency":"NGN", "current_balance": "54321" }

Consolidated Financial Data Webhook JSON Encoded POST » http://your-callback-url

For every successful financial data retrieval, UfitPay will send a (JSON Encoded) HTTP POST containing details of the retrieved data.

Sample webhook payload (json)
{ "event":"financialdata", "reference":"12345689abcdef", "account_id": "ahk387t4bd90383fev3eg973", "status":"retrieved", "account_bank_name":"Zenith Bank", "account_number":"0123456789", "account_name":"John Doe", "account_currency":"NGN", "current_balance": "12200", "month_salary": "118000", "annual_salary": "1480000", "last_salary_date": "2022-11-28", "last_salary_amount": "120000", "month_income": "118000", "annual_income": "1450000", "max_income": "123000", "last_income_date": "2022-11-29", "month_expense": "90800", "annual_expense": "1234000", "total_loans": "0", "repaid_loans": "0" }

Bank Account Statement Webhook JSON Encoded POST » http://your-callback-url

For every successful bank account statement retrieval, UfitPay will send a (JSON Encoded) HTTP POST containing details of the retrieved data.

Sample webhook payload (json)
{ "event":"bankstatement", "reference":"12345689abcdef", "account_id": "ahk387t4bd90383fev3eg973", "status":"retrieved", "account_bank_name":"Zenith Bank", "account_number":"0123456789", "account_name":"John Doe", "account_currency":"NGN", "current_balance": "12200" "data" [ { "type": "debit", "date": "2022-07-28 12:55:00", "amount": "4700", "narration": "VC POS Loc-215016609012-ABCD", "balance": "12200", "channel": "online_transactions" }, { "type": "credit", "date": "2022-07-13 16:32:05", "amount": "1230", "narration": "NIP/WBP/UFITPAY-JAMES BOND", "balance": "16900", "channel": "transfer" } ] }

Virtual Card Transaction WebhookJSON Encoded POST » http://your-callback-url

For every debit transaction that occur on your virtual card, UfitPay will send a (JSON Encoded) HTTP POST containing details of the transaction to the callback URL set on the card.

Sample webhook payload (json)

{ "event":"card_transaction", "card_id": "ahk387t4bd90383fev3eg973", "amount": "16.0", "fees": "1.70", "balance": 27.87, "type": "debit", "currency": "USD", "reference": "bd793gdcp3097fyvs", "date": "2022-12-25 17:45-32", "narration": "GOOGLE-PAY CH539603", "card_pan": "4558-****-****-9676" }

Virtual Card OTP WebhookJSON Encoded POST » http://your-callback-url

Whenever an OTP is required to complete a transcation on your virtual card, UfitPay will send a (JSON Encoded) HTTP POST containing the generated OTP to the callback URL set on the card.

Sample webhook payload (json)

{ "event":"card_otp", "card_id": "ahk387t4bd90383fev3eg973", "otp": "123", "datetime": "2022-12-25 17:45-32", "request_source": "GOOGLE-PLAY", "card_pan": "4558-****-****-9676" }

Virtual Card Transaction Declined WebhookJSON Encoded POST » http://your-callback-url

Whenever a transcation attempt on your virtual card is declined, UfitPay will send a (JSON Encoded) HTTP POST to the callback URL set on the card.

Sample webhook payload (json)

{ "event":"card_transaction_declined", "card_id": "ahk387t4bd90383fev3eg973", "status": "declined", "amount": "2.50", "fees": "0.50", "reason": "insufficient balance", "datetime": "2022-12-25 17:45-32", "request_source": "ALIEXPRESS", "card_pan": "4558-****-****-9676" }