Skip to main content

Web or Javascript

Our Checkout library provides a simple integration with your website to accept payments. You can open our checkout either as a popup modal window above your page or can simply redirect to our checkout and get control back using a callback URL.

SAMPLE EXPERIENCE
  • To see our checkout in action, visit the live demo store and perform a live transaction.
  • Both the popup modal window and redirect experiences are available for you to try out.

Compatibilities and Dependencies​

The Nimbbl Checkout library works with all modern browsers that support ES6 modules and JavaScript. Supported browsers include:

  • Chrome: Version 61+ (supports ES6 modules)
  • Firefox: Version 60+ (supports ES6 modules)
  • Safari: Version 10.1+ (supports ES6 modules)
  • Edge: Version 16+ (Chromium-based Edge) and Edge Legacy 15+
  • Opera: Version 48+
  • Mobile Browsers: iOS Safari 10.3+, Chrome Mobile 61+
Opening Checkout in Mobile WebView

If you're integrating the Nimbbl Web checkout in a mobile WebView (Android, iOS, React Native, or Flutter), you'll need to handle UPI app redirects properly. When users select a UPI app on the checkout page, the app needs to intercept the UPI app URL and open it natively. See our Mobile WebView for detailed platform-specific implementation instructions.

Import / Add the Checkout library​

Import the Nimbbl Checkout JSSDK within your script tag using type="module" and the defer attribute to ensure it loads asynchronously and supports modern JavaScript modules before initializing the checkout. Refer to sample code below.

import Checkout from "https://cdn.jsdelivr.net/npm/nimbbl_sonic@latest";

Initialize Checkout​

Initialize the Checkout class by providing your unique token obtained from previous step. This step should be performed on the same page where you intend to launch the checkout.

Option PropertiesTypeMandatory?Description
tokenstringtrueThis would have been generated from your server during order creation using V3 create-order API.
import Checkout from "https://cdn.jsdelivr.net/npm/nimbbl_sonic@latest";
const checkout = new Checkout({ token: "your_token_here" });

Launching the Nimbbl Checkout​

Understanding Checkout Options​

Read more about options object and its properties below.

Nimbbl provides you with two ways of receiving the response from SDK. This mode also determines the way in which your checkout is launched. One of the mode is, callback_handler which launches the Nimbbl Checkout within a popup modal window, alternative to this we have callback_url where the Checkout opens in the same window by redirecting users away from your page.

Option PropertiesTypeMandatory?Description
callback_handlerfunctionRequired if callback_url is not passed.Handler Function will open Nimbbl checkout in a popup modal window. On successful or failure payment, customer will get the json response with status.
callback_urlstringRequired if callback_handler is not passed.Checkout opens in the same window by redirecting away from your page. On successful or failure payment, customer will be redirected to the specified Callback URL, for example, a payment success page.

Nimbbl lets you enforce a payment mode on the Checkout. This can be done by passing the payment_mode_code property. There are other related properties in to each different payment mode, you can read it in the table below. If you don't pass payment_mode_code the customer is shown the full Checkout with all available payment modes.

Option PropertiesTypeMandatory?Description
payment_mode_codestringfalseIn case of specific payment mode, this property is mandatory. Possible values net_banking, card, upi, wallet, emi. If you don't pass payment_mode_code the customer is shown the full Checkout with all available payment modes.
bank_codestringfalseOnly to be passed in case of net_banking. Example: hdfc. To get the full list of banks supported for you, please use this API. If it isn't passed, Checkout will open with a page for the user to choose their bank from enabled banks
wallet_codestringfalseOnly to be passed in case of wallet. Example: jio_money. To get the full list of wallets supported for you, please use this API. If it isn't passed, Checkout will open with a page for the user to choose their wallet from enabled wallets
payment_flowstringfalseOnly to be passed in case of upi to determine the flow. Possible value is intent. If it isn't passed, Checkout will open with page for the user to pay using a QR or choose a UPI app
upi_app_codestringfalseOnly to be passed in case of upi and payment_flow is intent. Possible values phonepeupi, gpay. Checkout will open with the transaction initiated for the upi app passed in the upi_app_code field. If it isn't passed, Checkout will show a UPI QR or prompt user to choose a UPI app
emi_codestringfalseOnly to be passed in case of emi. Possible values debit, credit, cardless. If it isn't passed, Checkout will show all available EMI options

Setting the Checkout Options​

Set all the relevant properties for your use case in the options object as shown below

var options = {
  // pass `callback_handler` if you want to open the Checkout in a popup modal.
  callback_handler: function (response) {
    alert(response);
  },

  // only if you want to enforce a specific payment mode
  payment_mode_code: string,
  bank_code: string,
  wallet_code: string,
  payment_flow: string,
  upi_app_code: string,
  emi_code: string,
};

Invoking the Checkout​

Finally, after setting up the options object with respective parameters, we can now invoke checkout by accessing checkout method.

checkout.open(options);

Capture Transaction Response​

The final step in completing the client integration is capturing the response and sending it to your server

Checkout with Handler Function​

If you used the sample code with the handler function, then:

"callback_handler": function (response){
    // Process the response here and
    // send  the response to your server for processing
}

Checkout with Callback URL​

Provided below is a detailed example that demonstrates all the code that you need to do to accept payments on your web page. Please note this example covers the popup modal flow using the callback_handler.

callback_url?response=base64_payload

You will need to decode the base64 payload. To learn how to decode the payload, you can refer here. The decoded response will need to be sent to your server.

Summary of Changes​

Provided below are detailed examples that demonstrate all the code you need to accept payments on your web page. The examples cover the popup modal flow using the callback_handler.

  • Integration: To integrate Nimbbl Checkout, include the provided script tag in your HTML document using type="module" and the defer attribute. This ensures the script asynchronously imports the Nimbbl Checkout module from the CDN and supports modern JavaScript modules.
  • Initialization: Create a new instance of the Nimbbl Checkout class with your authentication token.
  • Configuration: Define payment options such as callback handler, payment mode code, bank code, wallet code, payment flow, UPI ID, and UPI app code.
  • Opening Checkout: Call the open() method on the Checkout instance with the configured options to open the checkout.
  • Capturing Response: To finalize client integration, capture transaction response and forward it to your server. If utilizing a handler function, process the response within it. For callback URL usage, decode the base64 payload and transmit the decoded response to your server for processing.
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nimbbl Checkout Integration</title>
    <link rel="stylesheet" href="style.css" />

    <!-- DNS prefetch for external domains -->
    <link rel="dns-prefetch" href="//cdn.jsdelivr.net" />

    <!-- Preconnect to external domains for faster connection -->
    <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin />
  </head>
  <body>
    <div>
      <button id="checkoutBtn" class="checkout-button">
        Proceed to Checkout
      </button>
    </div>

    <!-- Load main checkout logic with defer -->
    <script defer>
      // Initialize checkout function with improved error handling
      async function initializeCheckout(token) {
        try {
          // Load Nimbbl Sonic module with timeout
          const checkoutPromise = import(
            "https://cdn.jsdelivr.net/npm/nimbbl_sonic@latest"
          );

          // Add timeout for module loading
          const timeoutPromise = new Promise((_, reject) => {
            setTimeout(
              () => reject(new Error("Module loading timeout")),
              10000
            );
          });

          const checkoutModule = await Promise.race([
            checkoutPromise,
            timeoutPromise,
          ]);
          const Checkout = checkoutModule.default;

          const checkout = new Checkout({ token: token });

          const options = {
            callback_handler: function (response) {
              console.log("Payment response:", response);
            },
          };

          checkout.open(options);
        } catch (error) {
          console.error("Failed to load checkout:", error);
        }
      }

      // Main checkout flow
      async function handleCheckout() {
        try {
          // this token should be generated by the merchant S2S
          const token =
            "YOUR_TOKEN_HERE";

          if (!token) {
            throw new Error("No token received from order creation");
          }

          // Step 2: Initialize and open checkout
          await initializeCheckout(token);
        } catch (error) {
          console.error("Checkout failed:", error);
        }
      }

      // Wait for DOM to be ready before adding event listeners
      document.addEventListener("DOMContentLoaded", function () {
        const checkoutBtn = document.getElementById("checkoutBtn");
        if (checkoutBtn) {
          checkoutBtn.addEventListener("click", handleCheckout);
        }
      });
    </script>
  </body>
</html>
IMPORTANT
  • Share the response parameters received to your server
  • This will need to be validated on your server before you decide to provide goods or services
  • More details available on processing the response in Completing the Integration
Creating an OrderRequired server-side configurationStandard Checkout OverviewIntegration overviewSonic Product OverviewWhat customers see