JavaScript (elements) Checkout SDK

BoxPay Checkout SDK enables you to use BoxPay Payments Elements and use them in your payment flow. 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 checkout SDK –

Payment Flow

The shopper taps on the Pay button on the Merchant’s website.
The Merchant Server processes the request and initiates a checkout session via the Create Checkout Session API.
The Merchant Server receives the BoxPay Checkout URL in the response and returns it back to Merchant’s website.
Merchant website initiates the BoxPay payment flow by invoking JavaScript Elements SDK.
The shopper completes the payment on the checkout page.
After payment, BoxPay calls the onPayment callback function with the inquiryToken.
The Merchant Server uses the Payment Inquiry API to verify the payment status based on the received inquiryToken.
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.

Integration Steps

1. 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-web-sdk@1.0/dist/boxpay.esm.min.js"></script>

2. Add HTML Elements

Include the necessary containers in your HTML for the payment element and external pay button in the <body> section

Example:

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

3. Initialize the SDK & Configure Checkout Element

Use the elements method to mount the checkout form in the container with id=”payment-element”.

Example:

<script>
const shopperDetails = {
  email: "example@boxpay.com",
  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'],
    
    // Optional: shopperDetails - If provided, these details will be used and will override 
    // the details fetched from the session token. If not provided, the details from the 
    // session token will be used automatically.
    shopperDetails: shopperDetails,
    
    mode: "development", // "production"
    
    // Optional: appearance - If provided, these styling options will be applied to customize
    // the checkout UI. If not provided, default styling will be used.
    appearance: {
      primaryColor: "#ffd042",
      secondaryColor: "#ff0000",
      primaryTextColor: "#555",
      secondaryTextColor: "#666",
      payButton: {
        borderRadius: "8px",
        fontSize: "1rem",
        padding: "0.5rem 1rem",
        color: "#fff",
        width: "100%"
      }
    },
    
    options: {
      payButton: {
        // show (boolean): Set to true if you want to use the SDK's built-in pay button.
        // Set to false if you want to use your own custom pay button.
        // - If true: No need to pass handlePayButtonValidity function or call initiatePayment()
        // - If false: Must pass handlePayButtonValidity function and manually call initiatePayment()
        show: false,
        
        // onPaymentButtonValidity: Only required when show is false (using your own button).
        // This callback receives a boolean indicating if the payment form is valid.
        // Use this to enable/disable your custom pay button.
        onPaymentButtonValidity: handlePayButtonValidity,
      },
    },
    
    onLoad: handlePaymentElementLoad, // fires when payment element is loaded
    onPayment: handleOnPayment
  });
}

mountBoxpayCheckout();

function handlePaymentElementLoad(data) {
  console.log(data);
  
  // initiatePayment(): Only call this function when you are using your own custom pay button
  // (i.e., when payButton.show is false). This triggers the payment process.
  // If you're using the SDK's built-in button (payButton.show is true), this is handled automatically.
  const resp = await checkoutInstance.initiatePayment();
}

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

function handlePayButtonValidity(isValid) {
  // Enable or disable your custom pay button based on the isValid parameter
  // This function is only needed when using your own pay button (payButton.show is false)
}
</script>

4. Callback Functions

4.1 onLoad:

This callback function is triggered when the payment element is successfully loaded. Use it to initiate the payment event and display the external pay button.
Additionally, it may receive messages if any issues are encountered during the loading process.
For example, in case of token for which payment was already completed, the message will be:

{
    "message": "Payment Elements Loaded"
}

4.2 handleOnPayment:

This callback function is used to process the payment response. It receives payment completion data for any payment status, such as SUCCESS or FAILURE.

function handleOnPayment(data) {
  console.log(data);
  // Add merchant-specific logic to handle the payment response
}

Sample Response (SUCCESS):

{
    "token": "<sessionToken>",
    "status": "PAID",
    "statusReason": "Approved by PSP",
    "reasonCode": "OS_0000",
    "transactionId": "123xyy123",
    "transactionTimestamp": "2026-01-05T10:28:41.963411474Z",
    "amount": 84000,
    "currencyCode": "INR",
    "paymentCompleted": true,
    "originalAuthAmount": 100,
    "currencySymbol": "₹",
    "totalAmount": 100,
    "transactionTimestampLocale": "05/01/2026 15:58:41 IST",
    "amountLocale": "100"
}

4.3 onPaymentButtonValidity:

This callback function will receive Boolean value that will enable/disable external pay button.

function handlePayButtonValidity(isValid) {
  // Enable or disable your custom pay button based on the isValid parameter
  // This function is only needed when using your own pay button (payButton.show is false)
}

Key Configuration Options

Option	Description	Example
container	DOM ID where the payment element will be rendered	‘payment-element’
paymentMethods	List of payment methods to enable	[‘card’]
shopperDetails	Shopper details for pre-filling the checkout form	{ email: “example@boxpay.com”, firstName: “John”, lastName: “Doe”, phoneNumber: “+911111111111”, deliveryAddress: { address1: ‘123 Main St’, address2: ‘Suite 1’, city: ‘New York’, state: ‘NY’, countryCode: “US”, postalCode: “10001” `} };`
options.payButton.show	Whether to show the default SDK pay button	False

BoxPay Payments