Inline Integrations

  • Home
  • Inline Integrations

Introduction


Quickly embed UfitPay merchant payment features in your website or app using our Inline JavaScript integration flow

Our JavaScript inline integration option allows you to easily add different UfitPay merchant payment features and other financial data on your page or application with minimal coding, using the initializePayWithUfitPay() JavaScript function. Our inline function responds to your request in accordance with your request configurations. If you specify a callback_url in your request, the function will send applicable callback data to the provided URL when the request is completed.

You can also have our inline function invoke other javaScript functions on your site or app by passing the function name in callback_function.

Integrating Merchant Inline Features

To use our merchant inline features, you must first Include the UfitPay inline javaScript Library within the <body> tags of your HTML page as shown below, replacing {Your-Merchant-API-Key} with your actual UfitPay merchant API Key

<script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script>

Sandbox Credentials

The following Credentials can be used for development and test purpose only. Transactions done using these credentials are not treated as live

Merchants API Key VENDWCB5TO5RfJFCNkwSX8z0F8ZwD91
Internet Banking Username 1100000011
Internet Banking Password 12345678
PIN / OTP / Token 123456

Invoking UfitPay Inline Function

After you have included the UfitPay JavaScript Library within your app, next thing is to invoke our initializePayWithUfitPay() Javascript function, passing an object containg all necessary parameters as required by the inline feature being integrated (see integration samples below).

<script> initializePayWithUfitPay({ resource: "{resource-name}", parameter-name: "parameter-value" }); </script>

You can invoke the initializePayWithUfitPay() function programatically or bind them to some sort of button click event.

Inline Function Objects

resource (string) (required) Set this "paymentlink" for Tokenized Payment Link integration, "mobileairtime" for Airtime payment, "disposableaccount" for Disposable Bank Account payments integration, "financialdata" for Consolidated Financial Data retrieval integration, "accountbalance" for bank balance retrieval, "bankstatement" for Bank Statement retrieval integration or "directdebit" for Direct Bank Debit integratiion
payer_name (string) (required for Airtime payment, Tokenized payment integrations) This is the customer / payer name. The value passed here will be used as Bank Account Name for disposable account payment integrations
service_code (string) (required only for Tokenized payment integrations) This is your assigned Service Code for the service. You can find this under My Services on your Merchant Dashboard
payer_email (string) (required for Airtime payment, Tokenized payment and direct bank debit integrations) This is the Payer's contact email address.
customer_identifier (string) (required for Tokenized payment integrations) This is the unique customer / payer identifier for the service.
account_number (string) (optional) This is only applicable to bank statement, bank balance or consolidated financial data integarations. If supplied, our system will report the request as failed if this value doesnt match the customer's account number on connection with the bank
statement_period (string) (required for bank statement integrations) This is the period (in months) you wish to return statement for. This can be any numerical value between 1 and 12
amount (string) (required for Airtime payment, Tokenized payment and direct bank debit integrations) This is the expected amount to be paid or debited in Naira.
description (string) (required for Airtime payment and direct bank debit integrations) This is the expected amount to be paid or debited in Naira.
mandate_type (string) (required for direct bank debit integrations) This is the mandate type to create with the payer's bank. Set this to "onetime" for one-time debits or "recurring" for recurring debits. Default value is "onetime". In case of recurring mandates, a re-usable auth token will be returned in the json callback response, which can be used to initiate new debit of same amount at any future time
reference (string) (required) This is Your Unique payment tracking reference. If supplied, this can also be used to validate status of a payment using the verify_payment endpoint for payment integrations.
callback_url (string) (optional) This is a custom URL you would like notification callback payload sent to for this request. 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 request is completed or canceled. This is only applicable to payment link integarations
validity (string) (required for only disposableaccount integrations) This is the duration in minutes to retain the virtual bank account. The value must be between 5 and 30. Default value is 30
callback_function (string) (optional) This is a custom javaScript function name you would like to use for handling inline payment callback events.

Inline Callback Object Properties

Our inline function will pass an object to your callback function (if defined) with the following properties upon completion of the request;

reference (string) This is same Unique request reference you supplied during your request.
event (string) This contains the inline event. This can be either "completed" for successful payments / requests or "failed" for unsuccessful payments/requests.
status (string) This is descriptive status of the payment / request.
data (base64 encoded string) This is a base64 encoded string containing any expected data in json format. The data returned here is thesame as that sent to your callback URL.

For payment integrations, we strongly recommend you verify the responses by calling the verify_payment endpoint before giving value to the payer. Refer to Payment Verification API for more


Payment Link Integration

Below is a sample implementation of our Inline Payment Link. Please note that this integration requires a Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Pay with UfitPay</button> <!-- Invoke UfitPay inline payment function when your payment button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "paymentlink", payer_name: "John Doe", payer_email: "example@email.com", amount: "2000", customer_identifier: "123456", reference: "12345689abcdef", validity: "30", service_code: "wallet", callback_url: "https://example.com/call_back_script", return_url: "https://example.com/thank_you_page", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Payment reference: "+data.reference+", Payment status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Payment has been successfully completed } else { // Payment wasnt done yet or has failed } } </script>

Upon completion of payment, we strongly recommend you verify the status of the transaction by calling the verify_payment endpoint using value returned under data.reference before giving value to the payer. Refer to Payment Verification API for more

We will also send a (Form Encoded) HTTP POST containing details of the payment to your callback URL (If provided during setup or passed via callback_url with the API call). Refer to Payment Notification Webhook for more information on how to handle this



Airtime Payment Integration

Below is a sample implementation of our Inline Airtime Payment featire. Please note that this integration requires a Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Pay with UfitPay</button> <!-- Invoke UfitPay inline payment function when your payment button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "mobileairtime", payer_name: "John Doe", payer_email: "example@email.com", description: "Payment for ABCD", amount: "2000", reference: "12345689abcdef", callback_url: "https://example.com/call_back_script", return_url: "https://example.com/thank_you_page", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Payment reference: "+data.reference+", Payment status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Payment has been successfully completed } else { // Payment wasnt done yet or has failed } } </script>

Upon completion of payment, we strongly recommend you verify the status of the transaction by calling the verify_payment endpoint using value returned under data.reference before giving value to the payer. Refer to Payment Verification API for more

We will also send a (Form Encoded) HTTP POST containing details of the payment to your callback URL (If provided during setup or passed via callback_url with the API call). Refer to Payment Notification Webhook for more information on how to handle this



Disposable Account Integration

Below is a sample implementation of our Inline Disposable Bank Account payment feature. Please note that this integration requires a Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Pay with UfitPay</button> <!-- Invoke UfitPay inline payment function when your payment button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "disposableaccount", payer_name: "John Doe", payer_email: "example@email.com", amount: "2000", reference: "12345689abcdef", validity: "30", callback_url: "https://example.com/call_back_script", return_url: "https://example.com/thank_you_page", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Payment reference: "+data.reference+", Payment status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Payment has been successfully completed } else { // Payment wasnt done yet or has failed } } </script>

Upon completion of payment, we strongly recommend you verify the status of the transaction by calling the verify_payment endpoint using value returned under data.reference before giving value to the payer. Refer to Payment Verification API for more

We will also send a (Form Encoded) HTTP POST containing details of the payment to your callback URL (If provided during setup or passed via callback_url with the API call). Refer to Payment Notification Webhook for more information on how to handle this



Bank Balance Integration

Below is a sample implementation of Customer Bank Balance Retrieval feature. Please note that this integration requires a UfitPay a Wallet Enabled Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Connect Account</button> <!-- Invoke UfitPay inline payment function when your button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "accountbalance", account_number: "0123456789", reference: "12345689abcdef", callback_url: "https://example.com/call_back_script", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Request reference: "+data.reference+", Request status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Retrieval has been successfully completed // Decode the returned value under data.data to get callback json object var callbackJsonObj = JSON.parse(atob(data.data)); var requestStatus = callbackJsonObj.status; //retrieved or pending var accountBalance = callbackJsonObj.current_balance; var accountNumber = callbackJsonObj.account_number; var accountName = callbackJsonObj.account_name; var accountCurrency = callbackJsonObj.account_currency; var accountBankName = callbackJsonObj.account_bank_name; } else { // Authorization wasnt done yet or has failed } } </script>

Upon successful retrieval of the customer's balance, the following json payload is sent to your callback URL with details of the retrieved data;

{ "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" }

We will also send the following object as a parameter to your javascript callback function (if supplied);

{ "event":"completed, failed or canceled", "status":"Request Completed, Request Canceled, Request Failed", "reference": "Same reference you passed to us in your integration", "data": "base64 encoded json having same payload as the one we sent to your callback url above" }

Note: If the value returned under data.status is "pending", it indicates the customer's bank data is still being retrieved from the bank. In that case, we will POST the retrieved data to your callback URL once it is ready.
]

Tip: It is recommended that you capture and save the value returned under data.account_id as you will need that in case you want to request an updated account balance information for the customer in the future. Refer to Updated Financial Data Retrieval API for more information on this.



Consolidated Financial Data Integration

Below is a sample implementation of Customer Financial Data Retrieval feature. Please note that this integration requires a UfitPay a Wallet Enabled Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Connect Account</button> <!-- Invoke UfitPay inline payment function when your button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "financialdata", account_number: "0123456789", reference: "12345689abcdef", callback_url: "https://example.com/call_back_script", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Request reference: "+data.reference+", Request status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Retrieval has been successfully completed // Decode the returned value under data.data to get callback json object var callbackJsonObj = JSON.parse(atob(data.data)); var requestStatus = callbackJsonObj.status; //retrieved or pending var accountBalance = callbackJsonObj.current_balance; var accountNumber = callbackJsonObj.account_number; var accountName = callbackJsonObj.account_name; var accountCurrency = callbackJsonObj.account_currency; var yearlyIncome = callbackJsonObj.annual_income; var yearlyExpense = callbackJsonObj.annual_expense; var accountBankName = callbackJsonObj.account_bank_name; var monthlyIncome = callbackJsonObj.month_income; var monthlyExpense = callbackJsonObj.month_expense; var highestIncome = callbackJsonObj.max_income; var lastIncomeDate = callbackJsonObj.last_income_date; var monthlySalary = callbackJsonObj.month_salary; var yearlySalary = callbackJsonObj.last_salary_amount; var lastSalaryDate = callbackJsonObj.last_salary_date; var lastSalaryAmount = callbackJsonObj.last_salary; var loandCollevcted = callbackJsonObj.total_loans; var loandRepaid = callbackJsonObj.repaid_loans; } else { // Authorization wasnt done yet or has failed } } </script>

Upon successful retrieval of the customer's financial data, the following json payload is sent to your callback URL with details of the retrieved data;

{ "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" }

We will also send the following object as a parameter to your javascript callback function (if supplied);

{ "event":"completed, failed or canceled", "status":"Request Completed, Request Canceled, Request Failed", "reference": "Same reference you passed to us in your integration", "data": "base64 encoded json having same payload as the one we sent to your callback url above" }

Note: If the value returned under data.status is "pending", it indicates the customer's bank data is still being retrieved from the bank. In that case, we will POST the retrieved data to your callback URL once it is ready.

Tip: It is recommended that you capture and save the value returned under data.account_id as you will need that in case you want to request an updated financial data for the customer in the future. Refer to Updated Financial Data Retrieval API for more information on this.



Bank Statement Integration

Below is a sample implementation of our Bank Statement Retrieval feature. Please note that this integration requires a UfitPay wallet-enabled Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Share Account Statement</button> <!-- Invoke UfitPay inline payment function when your payment button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "bankstatement", account_number: "0123456789", statement_period: 12, reference: "12345689abcdef", callback_url: "https://example.com/call_back_script", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Payment reference: "+data.reference+", Payment status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Retrieval has been successfully completed // Decode the returned value under data.data to get callback json object var callbackJsonObj = JSON.parse(atob(data.data)); var requestStatus = callbackJsonObj.status; //retrieved or pending var accountStatementObj = callbackJsonObj.data; } else { // Authorization wasnt done yet or has failed } } </script>

Upon successful retrieval of the customer's bank statement, the following json payload is sent to your callback URL with details of the retrieved bank statement;

{ "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" } ] }

We will also send the following object to your javascript callback function (if supplied);

{ "event":"completed, failed or canceled", "status":"Request Completed, Request Canceled, Request Failed", "reference": "Same reference you passed to us in your integration", "data": "base64 encoded json having same payload as the one we sent to your callback url above" }

Note: If the value returned under data.status is "pending", it indicates the customer's bank statememnt is still being retrieved from the bank. In that case, we will POST the retrieved data to your callback URL once it is ready.

Tip: It is recommended that you capture and save the value returned under data.account_id as you will need that in case you want to request an updated account statement for the customer in the future. Refer to Updated Financial Data Retrieval API for more information on this.



Direct Bank Debit Integration

Below is a sample implementation of our Direct Bank Debit payment feature. Please note that this integration requires a Merchant API Key.

<!-- Include the UfitPay inline javaScript Library within the <body> tags of your HTML page. Remember to replace {Your-Merchant-API-Key} with your actual UfitPay merchant API Key --> <script src="https://embed.ufitpay.com/{Your-Merchant-API-Key}"></script> <!-- Render your payment button with a unique element ID assigned --> <button type="button" id="my_paynow_button">Pay with UfitPay</button> <!-- Invoke UfitPay inline payment function when your payment button is clicked --> <script> document.getElementById("my_paynow_button").onclick = function(){ initializePayWithUfitPay({ resource: "directdebit", payer_name: "John Doe", payer_email: "example@email.com", amount: "2000", description: "Payment for ABCD", mandate_type: "onetime", customer_identifier: "123456", reference: "12345689abcdef", callback_url: "https://example.com/call_back_script", return_url: "https://example.com/thank_you_page", callback_function: "handleCallback" }); }; /* Create a javaScript function to handle callback events */ function handleCallback(data){ console.log("Payment reference: "+data.reference+", Payment status: "+data.event+", Status message: "+data.status); if(data.event=="completed") { // Payment has been successfully completed // Decode the returned value under data.data to get callback json object var callbackJsonObj = JSON.parse(atob(data.data)); var recurringDebitAuthToken = callbackJsonObj.auth_token; } else { // Payment wasnt done yet or has failed } } </script>

Upon completion of payment, we strongly recommend you verify the status of the transaction by calling the verify_payment endpoint using value returned under data.reference before giving value to the payer. Refer to Payment Verification API for more

We will also send a (Form Encoded) HTTP POST containing details of the payment to your callback URL (If provided during setup or passed via callback_url with the API call). Refer to Payment Notification Webhook for more information on how to handle this