BoxPay Checkout JS SDK

A lightweight, secure, and customizable checkout experience for payments — built to embed directly inside merchant websites or open in a standalone checkout window.

🚀 Features

• Supports multiple payment methods
• Plug-and-play integration
• Customizable UI and appearance
• Works in both embedded mode or hosted checkout window
• Event handlers for full control
• Lightweight and dependency-free

📦 Installation

Via CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/boxpay-checkout-web-sdk.js"></script>

⚙ Usage Overview

You can use the SDK in two ways:

1. Embedded checkout UI inside your page (elements)
2. In-site checkout (open)

1️⃣ Embedded Checkout (Elements Integration)

This method renders the checkout UI directly into a container on your webpage.

HTML

<div id="payment-element"></div>

JS Integration

<script>
  const shopperDetails = {
    email: "[email protected]",
    firstName: "John",
    lastName: "Doe",
    phoneNumber: "+919999999999",
    deliveryAddress: {
      address1: "123 Main St",
      address2: "Suite 1",
      city: "New York",
      state: "NY",
      countryCode: "US",
      postalCode: "10001"
    }
  };

  const boxPay = new BoxPayCheckout("YOUR_SESSION_TOKEN");

  let checkoutInstance;

  async function mountBoxpayCheckout() {
    checkoutInstance = await boxPay.elements({
      container: "payment-element",
      paymentMethods: ['card'],
      shopperDetails: shopperDetails,
      mode: "development", // "production"
      appearance: {
        primaryColor: "#ffd042",
        secondaryColor: "#ff0000",
        primaryTextColor: "#555",
        secondaryTextColor: "#666",
        fontFamily:"'Poppins', sans-serif"  //"'Noto Sans', sans-serif",
        textInput: {
            textInputFocusBorderColor: '#ffd042',
            textInputBorderColor: '#000',
          },
        payButton: {
          borderRadius: "8px",
          fontSize: "1rem",
          padding: "0.5rem 1rem",
          color: "#fff",
          width: "100%",
          backgroundColor:"#ffd042"
        }
      },

      options: {
        siCheckboxState:"CHECKED_AND_DISABLED", //CHECKED_AND_DISABLED, CHECKED_AND_ENABLED, UNCHECKED_AND_ENABLED
        payButton: {
          show: false, 
          onPaymentButtonValidity: handlePayButtonValidity,
        },
      },
      onLoad: handlePaymentElementLoad // fires when payment element is loaded,
      onPayment: handleOnPayment
    });
  }

  mountBoxpayCheckout();

  function handlePaymentElementLoad(data) {
    console.log(data);
    // Add logic of your pay button and when pay button is clicked
    const resp = await checkoutInstance.initiatePayment();
  }

  function handleOnPayment(response) {
    console.log(response);
  }

  function handlePayButtonValidity(isValid) {
    // Enable external pay button if needed
  }
</script>

React Integration

import BoxPayCheckout from "boxpay-checkout-web-sdk";

let boxpayElements = null;

function App() {
    useEffect(() => {
        const boxPay = new BoxPayCheckout("YOUR_SESSION_TOKEN");
        async function mountElement() {
            boxpayElements = await boxPay.elements({
                container: "payment-element",
                paymentMethods: ["upi", "emi", "card", "wallet"],
                shopperDetails,
                appearance,
                onLoad: (data) => console.log("Payment element loaded", data),
                onPayment: (data) => console.log("Payment!", data),
                mode: "development",
                options: {
                    payButton: {
                        show: true, // use this flag to enable/disable external pay button
                        onPaymentButtonValidity: (data) => console.log("onPaymentButtonValidity!", data),
                    },
                },
            });
            mountElement();
        }
    },[]);
        
  return (
    <div className="App">
      <div id="payment-element"></div>
    </div>
  );
}

export default App;

🧭 Shopper Details Format

| Property | Type | Required | Description | | -------- | ---- | -------- | ----------- | | email | String | Yes | Shopper’s email address | | firstName | String | Yes | Shopper’s first name | | lastName | String | Yes | Shopper’s last name | | phoneNumber | String | Yes | Shopper’s mobile number including country code | | deliveryAddress | Object | Yes | Delivery or billing address details | | deliveryAddress.address1 | String | Yes | Primary address line | | deliveryAddress.address2 | String | No | Secondary address line (apartment, suite, etc.) | | deliveryAddress.city | String | Yes | City name | | deliveryAddress.state | String | Yes | State or region | | deliveryAddress.countryCode | String | Yes | ISO 2-letter country codeExample: US, IN | | deliveryAddress.postalCode | String | Yes | ZIP or postal code |

🎨 Appearance Customization

| Property | Type | Required | Description | | -------- | ---- | -------- | ----------- | | appearance | Object | No | Controls the visual styling of the checkout UI | | appearance.primaryColor | String | No | Primary theme color used across the checkout UI | | appearance.secondaryColor | String | No | Secondary color used for accents and highlights | | appearance.primaryTextColor | String | No | Color for primary text elements | | appearance.fontFamily | String | No | For updating font family | | appearance.secondaryTextColor | String | No | Color for secondary or helper text | | appearance.textInput.textInputFocusBorderColor | String | No | Border color for focused input | | appearance.textInput.textInputBorderColor | String | No | Border color for input | | appearance.payButton | Object | No | Custom styling options for the Pay button | | appearance.payButton.borderRadius | String | No | Border radius of the Pay buttonExample: "8px" | | appearance.payButton.color | String | No | Text color of the Pay button | | appearance.payButton.width | String | No | Width of the Pay buttonExample: "100%" | | appearance.payButton.fontSize | String | No | Width of the Pay buttonExample: "1rem" | | appearance.payButton.padding | String | No | Width of the Pay buttonExample: "0.5rem 1rem" | | appearance.payButton.backgroundColor | String | No | Background color of the Pay button |

⚙ Options

| Event | Type | Required | Description | | -------- | ---- | -------- | ----------- | | siCheckboxState | enum (CHECKED_AND_DISABLED, CHECKED_AND_ENABLED, UNCHECKED_AND_ENABLED) | No | Handles standing instruction checkbox behavior. if no value is passed then only one time payment (otp) will be done by default. | | payButton.show | boolean | No (default false) | If true then you are required to show your pay button in order make payment. | | onPaymentButtonValidity| boolean | Yes, (only when show is false) | Called whenever the form becomes valid or invalid that helps your pay button to enable or disable click. |

📡 Callback Events

| Event | Required | Description | | -------------------------| -------- | ------------------------------------------------------- | | onLoad | Yes | Triggered when the checkout UI is mounted | | onPayment | Yes | Triggered after payment success or failure | | onPaymentButtonValidity| Yes, (only when show is false) | Called whenever the form becomes valid or invalid that helps your pay button to enable or disable click. |

2️⃣ Full-Page Hosted Checkout (In-site)

This approach opens the hosted checkout in an iframe — no UI managed by the merchant.

HTML

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

JS Integration

<script>
  function handlePaymentResponse(data) {
    console.log("Payment!", data);
  }

  function handlePaymentCancellation() {
    console.log("Payment Cancelled!");
  }

  BoxPayCheckout.open(
    "https://checkout.boxpay.tech?token=YOUR_SESSION_TOKEN",
    handlePaymentResponse,
    handlePaymentCancellation
  );
</script>

This automatically loads the checkout and triggers callbacks on success/cancel.

🧪 Modes

mode: "development"  // or "production"

📝 License

Proprietary – authorized use only.

📬 Support

For technical integration help, reach your BoxPay onboarding manager or support channel.