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>

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 Financial Data retrieval integration, "bankstatement" for Bank Statement retrieval integration or "directdebit" for Direct Bank Debit integratiion
payer_name (string) (required for 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 paymentlink) This is your assigned Service Code for the service. You can find this under My Services on your Merchant Dashboard
payer_email (string) (required) This is the Payer's contact email address.
customer_identifier (string) (required for paymentlink) This is the unique customer / payer identifier for the service.
account_number (string) (optional) This is only applicable to bank statement or financial data integarations
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 payment and direct bank debit integrations) This is the expected amount to be paid or debited in Naira.
reference (string) (required) This is Your Unique request tracking reference. If supplied, this can also be used to validate status of the 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.

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>


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", 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>


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>


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 } 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;


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 } 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;


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", 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 } else { // Payment wasnt done yet or has failed } } </script>