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:

https://cdn.jsdelivr.net/npm/boxpay-checkout-js-sdk@1.1.1/dist/boxpay-checkout-js-sdk.min.js

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>
 <div id="<payment-element>"></div>
 <button id="<external-pay-button>">Pay</button>
</div>

3. Initialize the SDK

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

Initialize the BoxPayCheckout instance with the session token:

const boxPay = new BoxPayCheckout('YOUR_SESSION_TOKEN');

4. Configure Checkout Element

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

Example:

let boxpayCheckoutElements;
async function mountBoxpayCheckout() {
  boxpayCheckoutElements = await boxPay.elements({
    container: '<payment-element>',
    paymentMethods: ['card'], // pass payment methods here
    shopperDetails: <shopperDetails>,  //pass shopperDetails here
    onLoad: handlePaymentElementLoad, 
    onPayment: handleOnPayment, 
    options: {
      payButton: {
        show: false, // use this flag to enable/disable external pay button
        onPaymentButtonValidity: handlePayButtonValidity
      },
      cssFormClass: 'form-class', // custom CSS class for the form
    },
  });
}
mountBoxpayCheckout();

5. Integrate External Pay Button

Handle payment initiation onPayment via an external pay button:

function handlePaymentElementLoad(res) {
  console.log("Payment element loaded:", res);
  document.getElementById('<external-pay-button>').addEventListener('click', async () => {
    const resp = await boxpayCheckoutElements.initiatePayment();
    console.log("Payment initiated:", resp);
  });
}

6. Callback Functions

6.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: ‘Transaction has been already completed on this checkout token’
}

6.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.
Note: On SUCCESS, the data object will include an inquiryToken, which can be used to verify the payment status through the Payment Inquiry API.

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

Sample Response (SUCCESS):

{
status :”SUCCESS”,
inquiryToken: “<inquiryToken>”
}

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

function handlePayButtonValidity(isValid) {
        console.log("SDK pay valid::", isValid);
        const btnEl =  document.getElementById('external-pay-button');
        btnEl.disabled=!isValid;
      }

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	{ dateOfBirth: null, email: “example@boxpay.com”, firstName: “John”, gender: null, lastName: “Doe”, panNumber: “ABCDE1234F”, uniqueReference: “reference123”, 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
options.cssFormClass	CSS class applied to customize the form style	‘form-class’

Checkout Integration