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



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