JavaScript (in-site) Checkout SDK

BoxPay JS SDK enables you to display BoxPay hosted checkout right into your website. You may use this SDK to display BoxPay hosted checkout page into your website checkout or into a modal. We offer robust and seamless Javascript SDK ready for immediate use, allowing you to effortlessly accept payments from your shoppers.

To begin integrating with the BoxPay Checkout, the initial step is to register and setup your BoxPay account.

This outlines the typical workflow for integrating a BoxPay JS checkout SDK –

The shopper taps on the Buy/Pay button on the Merchant website.
The Merchant Server processes the request and initiates a checkout session through the Create Checkout Session API.
The Merchant Server receives the BoxPay Checkout url in the response and returns it back to Merchant website.
Merchant website initiates the BoxPay payment flow by invoking JavaScript Checkout SDK. Please refer to the JavaScript Checkout SDK Integration Steps section for more details around it.
The shopper completes the payment on the BoxPay Checkout Page.
After payment, BoxPay calls the payment completion callback method with the inquiry token.
The Merchant Server receives the inquiry token and verifies the payment status by utilising the Payment Inquiry API.
Based on the received payment status, the Merchant Server redirects the customer to the Order Confirmation page, displaying a customised message or to the payment failed/cancelled page.
Integrate webhooks to receive payment status notifications to cover cases where shopper chooses to exit the payments from BoxPay checkout page and/or fails to get redirected back to merchant website due to internet or other issues.

JavaScript Checkout SDK Integration Steps

Include the SDK Javascript

Add the BoxPay Checkout SDK to your webpage by including the following script tag in the <head> section of your HTML document:

<script src="https://cdn.jsdelivr.net/npm/boxpay-checkout-js-sdk@1.0.3/dist/boxpay-checkout-js-sdk.min.js"></script>

Create the required HTML structure

Create a container for the BoxPay Checkout iframe in your HTML body:

<div id="boxpay-checkout"></div>

You can style this container to fit your webpage’s design. For example, if you want the iframe to take up the full viewport height and width, in that case the configuration would be:

<style>
#boxpay-checkout {
    width: 100%;
    height: 100vh;
    overflow: hidden;
}
</style>

Initialize the payment

To initiate the payment flow, you need to call the open function of BoxPayCheckout class, passing in the checkout URL obtained from Create Checkout Session API, and following two callback functions to handle payment responses and cancellations.

Payment Completion Callback – This function is triggered when the payment process is completed. This callback is triggered with data input parameter containing inquiry token. Merchant website must send it to their server apis and then call Payment Inquiry API to fetch the payment status.
Payment Cancellation Callback – This function is triggered when the user clicks the back button on the checkout page.

Here’s an example of sample code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>BoxPay Payment SDK Example</title>
    <!-- Link to the SDK script file -->
    <script src="https://cdn.jsdelivr.net/npm/boxpay-checkout-js-sdk@1.0.3/dist/boxpay-checkout-js-sdk.min.js"></script>
    <style>
    /* Style for the container holding the iframe */
    body {
      margin: 0;
      padding: 0;
    }
    #boxpay-checkout {
      /* your style goes here */
    }
    </style>
  </head>
  <body>
    <div id="boxpay-checkout">
      <script>
      // This function is called when the payment is completed
      function handlePaymentResponse(data) {
        console.log('Payment completed!', data);
        // Merchant logic to handle payment response can be added here
      }

      // This function is called when the user navigates away from the checkout page
      function handlePaymentCancellation() {
        console.log('Payment Cancelled!');
        // Merchant logic to handle payment cancellation can be added here
      }

      // Initialize and open the BoxPayCheckout iframe with the provided token and callbacks
      // `handlePaymentResponse` will handle successful payments or errors
      // `handlePaymentCancellation` will handle the case where the user cancels the payment
      BoxPayCheckout.open('<checkout-url-received-from-create-session-api>', handlePaymentResponse, handlePaymentCancellation);
      </script>
    </div>
  </body>
</html>

Checkout Integration

JavaScript Checkout SDK Integration Steps

Include the SDK Javascript

Create the required HTML structure

Initialize the payment

How can we help?