TAP-Inlinejs

Popup Library for loading TAP's payment checkout gateway. It makes it easy to accept payments from a web application and to create custom, secure payment experiences for merchant apps and websites

Requirements

node >= 12.0.1
npm >= 6.0.0

Introduction

This documentation provides an overview of the TouchandPay Payment Popup (TAPPaymentPop) JavaScript library that facilitates payment integration with the TAP payment gateway. It explains how to use the library, describes its main features and provides an example of how to integrate it with a web page.

Version 2.0.5 (Latest)

Version 2.0.5 introduces a superMerchantFee parameter for advanced fee management and continues to use the env parameter to simplify environment selection (production or sandbox) with a single script URL.

Getting Started (v2.0.5)

To use the TAPPaymentPop JavaScript library (v2.0.5), include the following script tag in your HTML code:

<script src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>

You can now use the TAPPaymentPop.setup() method to create an instance of the payment gateway, passing in the required configuration parameters, including the new superMerchantFee parameter.

API (v2.0.5)

The TAPPaymentPop object provides the following methods:

• initialize(transactionDefaults): Initializes or re-initializes the payment gateway with specified default transaction parameters. Typically called by setup() if the gateway isn't already initialized.
• setup(transactionDetails, setupCallback): Configures and returns an instance of the payment gateway. transactionDetails is an object with configuration parameters. setupCallback is an optional function that receives the gateway instance.
• destroy(): Cleans up the current payment gateway instance, removing its iframes and event listeners. Call this if you need to remove the payment popup functionality from the page or before re-initializing with a completely new configuration.

The instance returned by TAPPaymentPop.setup() has the following method:

• openIframe(): Displays the payment gateway iframe to start the payment process.

Configuration Parameters (v2.0.5)

The TAPPaymentPop.setup() method requires a transactionDetails object with the following parameters:

| Parameter | Required | Description | | ------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | yes | Your TAP API key. | | env | yes | Environment to use: "production" for production or "sandbox" for testing. | | transID | yes | A unique transaction ID for this payment attempt. | | amount | yes | The amount of the transaction (e.g., in Kobo for NGN). | | email | yes | The email address of the customer. | | phone | if savePaymentDetails is true, then yes; else no | The customer's phone number. Required if savePaymentDetails is true. | | savePaymentDetails| no | Boolean (true/false). Set to true if you want to enable saving payment details for the customer. Defaults to false. | | customerReference | if savePaymentDetails is true, then yes; else no | A unique reference for the customer, used when savePaymentDetails is true. | | superMerchantFee | no | Optional fee amount for super merchant transactions. Used for advanced fee management scenarios. | | customPayload | no | An object for any other custom data you want to send with the transaction. This data will be nested under customPayload in the backend. | | - billerID | no (within customPayload) | The biller ID (Special Usecase, include in customPayload). | | - productID | no (within customPayload) | The product ID (Special Usecase, include in customPayload). | | - ... | no (within customPayload) | Other custom data relevant to your application. | | onClose | no | A function to call when the payment gateway popup is closed by the user before completion. | | callback | no | A function to call when the payment has been successfully completed. It receives the transaction response object as an argument. |

Example Usage (v2.0.5)

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>TAP Payment Gateway Example (v2.0.5)</title>
  </head>
  <body>
    <form id="pay-form">
      <div class="form-group">
        <label for="amount">Amount (Kobo)</label>
        <input type="number" id="amount" name="amount" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="email">Email</label>
        <input type="email" id="email" name="email" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="phone">Phone</label>
        <input type="text" id="phone" name="phone" class="form-control" /> <!-- Made not required in form for example flexibility -->
      </div>
      <div class="form-group">
        <label for="customerReference">Customer Reference (Optional)</label>
        <input type="text" id="customerReference" name="customerReference" class="form-control" />
      </div>
      <div class="form-group">
        <label>
          <input type="checkbox" id="savePaymentDetails" name="savePaymentDetails" />
          Save Payment Details
        </label>
      </div>
      <div class="form-group">
        <label for="superMerchantFee">Super Merchant Fee (Optional)</label>
        <input type="number" id="superMerchantFee" name="superMerchantFee" class="form-control" />
      </div>
      <div class="form-group">
        <label for="billerID">Biller ID (Optional)</label>
        <input type="text" id="billerID" name="billerID" class="form-control" />
      </div>
      <div class="form-group">
        <label for="productID">Product ID (Optional)</label>
        <input type="text" id="productID" name="productID" class="form-control" />
      </div>
      <button id="pay-btn" type="button" onclick="validateAndPay()" class="btn btn-primary">
        Pay
      </button>
    </form>
    <div id="alert-holder"></div>

    <script type="module" src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>
    <script>
      const api_key = "YOUR_API_KEY"; // Replace with your actual API key

      function validateAndPay() {
        const email = document.getElementById("email").value;
        const amount = document.getElementById("amount").value;
        const phone = document.getElementById("phone").value;
        const savePaymentDetails = document.getElementById("savePaymentDetails").checked;
        const customerReference = document.getElementById("customerReference").value;
        const superMerchantFee = document.getElementById("superMerchantFee").value;
        
        const billerID = document.getElementById("billerID").value;
        const productID = document.getElementById("productID").value;

        if (!email || !amount) { // Phone is conditionally required by the library
          alert("Please fill in Email and Amount.");
          return;
        }

        payWithTAP(email, amount, phone, savePaymentDetails, customerReference, superMerchantFee, billerID, productID);
      }

      function payWithTAP(email, amount, phone, savePaymentDetails, customerReference, superMerchantFee, billerID, productID) {
        const transactionDetails = {
          apiKey: api_key,
          env: "sandbox", // "production" or "sandbox"
          amount: parseFloat(amount),
          transID: `TAP-${Date.now()}-${Math.random().toString(36).slice(2)}`,
          email: email,
          phone: phone, 
          savePaymentDetails: savePaymentDetails,
          customerReference: customerReference,
          superMerchantFee: superMerchantFee ? parseFloat(superMerchantFee) : undefined,
          customPayload: {
            // phone: phone, // phone is a top-level param
            billerID: billerID || undefined,
            productID: productID || undefined,
          },
          callback: function (response) {
            console.log("Payment successful:", response);
            const msg = 'Success. The transaction id is <b>"' + response.transID + '"</b>. Full response: ' + JSON.stringify(response);
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-success" role="alert">' + msg + "</div>";
            document.getElementById("pay-form").reset();
          },
          onClose: function () {
            console.log("Payment popup closed by user.");
            const msg = "Payment popup closed. Please click the 'Pay' button to try again.";
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-info" role="alert">' + msg + "</div>";
          }
        };

        try {
            const handler = TAPPaymentPop.setup(transactionDetails);
            if (handler) {
                 handler.openIframe();
            } else {
                console.error("Failed to setup TAPPaymentPop. Check console for errors.");
                // Error messages from setup will be more specific if thrown by the library
            }
        } catch (error) {
            console.error("Error during TAPPaymentPop setup:", error);
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-danger" role="alert">' + error.message + "</div>";
        }
      }
    </script>
  </body>
</html>

Version 2.0.x (Previous)

Version 2.0.x introduces an env parameter to simplify environment selection (production or sandbox) and uses a single script URL.

Getting Started (v2.0.x)

To use the TAPPaymentPop JavaScript library (v2.0.x), include the following script tag in your HTML code:

<script src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>

You can now use the TAPPaymentPop.setup() method to create an instance of the payment gateway, passing in the required configuration parameters, including the new env parameter.

API (v2.0.x)

The TAPPaymentPop object provides the following methods:

• initialize(transactionDefaults): Initializes or re-initializes the payment gateway with specified default transaction parameters. Typically called by setup() if the gateway isn't already initialized.
• setup(transactionDetails, setupCallback): Configures and returns an instance of the payment gateway. transactionDetails is an object with configuration parameters. setupCallback is an optional function that receives the gateway instance.
• destroy(): Cleans up the current payment gateway instance, removing its iframes and event listeners. Call this if you need to remove the payment popup functionality from the page or before re-initializing with a completely new configuration.

The instance returned by TAPPaymentPop.setup() has the following method:

• openIframe(): Displays the payment gateway iframe to start the payment process.

Configuration Parameters (v2.0.x)

The TAPPaymentPop.setup() method requires a transactionDetails object with the following parameters:

| Parameter | Required | Description | | ------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | yes | Your TAP API key. | | env | yes | Environment to use: "production" for production or "sandbox" for testing. | | transID | yes | A unique transaction ID for this payment attempt. | | amount | yes | The amount of the transaction (e.g., in Kobo for NGN). | | email | yes | The email address of the customer. | | phone | if savePaymentDetails is true, then yes; else no | The customer's phone number. Required if savePaymentDetails is true. | | savePaymentDetails| no | Boolean (true/false). Set to true if you want to enable saving payment details for the customer. Defaults to false. | | customerReference | if savePaymentDetails is true, then yes; else no | A unique reference for the customer, used when savePaymentDetails is true. | | customPayload | no | An object for any other custom data you want to send with the transaction. This data will be nested under customPayload in the backend. | | - billerID | no (within customPayload) | The biller ID (Special Usecase, include in customPayload). | | - productID | no (within customPayload) | The product ID (Special Usecase, include in customPayload). | | - ... | no (within customPayload) | Other custom data relevant to your application. | | onClose | no | A function to call when the payment gateway popup is closed by the user before completion. | | callback | no | A function to call when the payment has been successfully completed. It receives the transaction response object as an argument. |

Example Usage (v2.0.x)

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>TAP Payment Gateway Example (v2.0.x)</title>
  </head>
  <body>
    <form id="pay-form">
      <div class="form-group">
        <label for="amount">Amount (Kobo)</label>
        <input type="number" id="amount" name="amount" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="email">Email</label>
        <input type="email" id="email" name="email" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="phone">Phone</label>
        <input type="text" id="phone" name="phone" class="form-control" /> <!-- Made not required in form for example flexibility -->
      </div>
      <div class="form-group">
        <label for="customerReference">Customer Reference (Optional)</label>
        <input type="text" id="customerReference" name="customerReference" class="form-control" />
      </div>
      <div class="form-group">
        <label>
          <input type="checkbox" id="savePaymentDetails" name="savePaymentDetails" />
          Save Payment Details
        </label>
      </div>
      <div class="form-group">
        <label for="billerID">Biller ID (Optional)</label>
        <input type="text" id="billerID" name="billerID" class="form-control" />
      </div>
      <div class="form-group">
        <label for="productID">Product ID (Optional)</label>
        <input type="text" id="productID" name="productID" class="form-control" />
      </div>
      <button id="pay-btn" type="button" onclick="validateAndPay()" class="btn btn-primary">
        Pay
      </button>
    </form>
    <div id="alert-holder"></div>

    <script type="module" src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>
    <script>
      const api_key = "YOUR_API_KEY"; // Replace with your actual API key

      function validateAndPay() {
        const email = document.getElementById("email").value;
        const amount = document.getElementById("amount").value;
        const phone = document.getElementById("phone").value;
        const savePaymentDetails = document.getElementById("savePaymentDetails").checked;
        const customerReference = document.getElementById("customerReference").value;
        
        const billerID = document.getElementById("billerID").value;
        const productID = document.getElementById("productID").value;

        if (!email || !amount) { // Phone is conditionally required by the library
          alert("Please fill in Email and Amount.");
          return;
        }

        payWithTAP(email, amount, phone, savePaymentDetails, customerReference, billerID, productID);
      }

      function payWithTAP(email, amount, phone, savePaymentDetails, customerReference, billerID, productID) {
        const transactionDetails = {
          apiKey: api_key,
          env: "sandbox", // "production" or "sandbox"
          amount: parseFloat(amount),
          transID: `TAP-${Date.now()}-${Math.random().toString(36).slice(2)}`,
          email: email,
          phone: phone, 
          savePaymentDetails: savePaymentDetails,
          customerReference: customerReference,
          customPayload: {
            // phone: phone, // phone is a top-level param
            billerID: billerID || undefined,
            productID: productID || undefined,
          },
          callback: function (response) {
            console.log("Payment successful:", response);
            const msg = 'Success. The transaction id is <b>"' + response.transID + '"</b>. Full response: ' + JSON.stringify(response);
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-success" role="alert">' + msg + "</div>";
            document.getElementById("pay-form").reset();
          },
          onClose: function () {
            console.log("Payment popup closed by user.");
            const msg = "Payment popup closed. Please click the 'Pay' button to try again.";
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-info" role="alert">' + msg + "</div>";
          }
        };

        try {
            const handler = TAPPaymentPop.setup(transactionDetails);
            if (handler) {
                 handler.openIframe();
            } else {
                console.error("Failed to setup TAPPaymentPop. Check console for errors.");
                // Error messages from setup will be more specific if thrown by the library
            }
        } catch (error) {
            console.error("Error during TAPPaymentPop setup:", error);
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-danger" role="alert">' + error.message + "</div>";
        }
      }
    </script>
  </body>
</html>

Version 1.0.x (Deprecated)

Note: Version 1.0.x is deprecated. Please upgrade to Version 2.0.5 for the latest features and a simplified environment setup.

Getting Started (v1.0.x - Deprecated)

To use the TAPPaymentPop JavaScript library, you need to first include the following script tag in your HTML code:

<!-- Production -->
<script src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>

<!-- Staging/Test -->
<script src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>

You can now use the TAPPaymentPop.setup() method to create an instance of the payment gateway, passing in the required configuration parameters.

API (v1.0.x - Deprecated)

The TAPPaymentPop object provides the following methods:

• initialize(transactionDefaults): Initializes or re-initializes the payment gateway with specified default transaction parameters. Typically called by setup() if the gateway isn't already initialized.
• setup(transactionDetails, setupCallback): Configures and returns an instance of the payment gateway. transactionDetails is an object with configuration parameters. setupCallback is an optional function that receives the gateway instance.
• destroy(): Cleans up the current payment gateway instance, removing its iframes and event listeners. Call this if you need to remove the payment popup functionality from the page or before re-initializing with a completely new configuration.

The instance returned by TAPPaymentPop.setup() has the following method:

• openIframe(): Displays the payment gateway iframe to start the payment process.

Configuration Parameters (v1.0.x - Deprecated)

The TAPPaymentPop.setup() method requires a transactionDetails object with the following parameters:

| Parameter | Required | Description | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | yes | Your TAP API key. | | transID | yes | A unique transaction ID for this payment attempt. | | amount | yes | The amount of the transaction (e.g., in Kobo for NGN). | | email | yes | The email address of the customer. | | customPayload | no | An object for any other custom data you want to send with the transaction. This data will be nested under customPayload in the backend. | | - billerID | no (within customPayload) | The biller ID (Special Usecase, include in customPayload). | | - productID | no (within customPayload) | The product ID (Special Usecase, include in customPayload). | | - ... | no (within customPayload) | Other custom data relevant to your application. | | onClose | no | A function to call when the payment gateway popup is closed by the user before completion. | | callback | no | A function to call when the payment has been successfully completed. It receives the transaction response object as an argument. |

Example Usage (v1.0.x - Deprecated)

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>TAP Payment Gateway Example (v1.0.x - Deprecated)</title>
  </head>
  <body>
    <form id="pay-form">
      <div class="form-group">
        <label for="amount">Amount (Kobo)</label>
        <input type="number" id="amount" name="amount" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="email">Email</label>
        <input type="email" id="email" name="email" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="phone">Phone</label>
        <input type="text" id="phone" name="phone" class="form-control" required />
      </div>
      <div class="form-group">
        <label for="billerID">Biller ID (Optional)</label>
        <input type="text" id="billerID" name="billerID" class="form-control" />
      </div>
      <div class="form-group">
        <label for="productID">Product ID (Optional)</label>
        <input type="text" id="productID" name="productID" class="form-control" />
      </div>
      <button id="pay-btn" type="button" onclick="validateAndPay()" class="btn btn-primary">
        Pay
      </button>
    </form>
    <div id="alert-holder"></div>

    <!-- Ensure you are using the correct version (e.g., Staging/Test for v1.0.3) -->
    <script type="module" src="https://unpkg.com/[email protected]/dist/umd/index.js"></script>
    <script>
      const api_key = "TkdLb2VUMk46ZXRoWEdJSEF0Z24xOnB1WVUzd3dvS1c4bw=="; // Replace with your actual API key

      function validateAndPay() {
        const email = document.getElementById("email").value;
        const amount = document.getElementById("amount").value;
        const phone = document.getElementById("phone").value;
        
        const billerID = document.getElementById("billerID").value;
        const productID = document.getElementById("productID").value;

        if (!email || !amount || !phone) {
          alert("Please fill in all required fields: Email, Amount, and Phone.");
          return;
        }

        payWithTAP(email, amount, phone, billerID, productID);
      }

      function payWithTAP(email, amount, phone, billerID, productID) {
        const transactionDetails = {
          apiKey: api_key,
          amount: parseFloat(amount),
          transID: `TAP-${Date.now()}-${Math.random().toString(36).slice(2)}`,
          email: email,
          customPayload: {
            phone: phone,
            billerID: billerID || undefined,
            productID: productID || undefined,
          },
          callback: function (response) {
            console.log("Payment successful:", response);
            const msg = 'Success. The transaction id is <b>"' + response.transID + '"</b>. Full response: ' + JSON.stringify(response);
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-success" role="alert">' + msg + "</div>";
            document.getElementById("pay-form").reset();
          },
          onClose: function () {
            console.log("Payment popup closed by user.");
            const msg = "Payment popup closed. Please click the 'Pay' button to try again.";
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-info" role="alert">' + msg + "</div>";
          }
        };

        try {
            const handler = TAPPaymentPop.setup(transactionDetails);
            if (handler) {
                 handler.openIframe();
            } else {
                console.error("Failed to setup TAPPaymentPop. Check console for errors.");
                document.getElementById("alert-holder").innerHTML = '<div class="alert alert-danger" role="alert">Could not initialize payment. Please check configuration.</div>';
            }
        } catch (error) {
            console.error("Error during TAPPaymentPop setup:", error);
            document.getElementById("alert-holder").innerHTML = '<div class="alert alert-danger" role="alert">' + error.message + "</div>";
        }
      }
    </script>
  </body>
</html>

Deployment (v1.0.x - Deprecated)

Inline JS is deployed to:

• Production: https://unpkg.com/[email protected]/dist/umd/index.js (Deprecated)
• Staging / Test: https://unpkg.com/[email protected]/dist/umd/index.js (Deprecated)
• npm: https://www.npmjs.com/package/tap-payment-popupjs (Check for latest v2.0.5)
• Test Sample (for v1.0.x): https://tap-sdk-demo-staging.netlify.app/

Live Checkout

Checkout Interface is deployed to:

• Live URL: https://checkout.touchandpay.me
• Sandbox URL: (The main checkout URL will adapt based on the env parameter in v2.0.5 For v1.0.x, use the Staging/Test script for a sandbox-like environment.)