XanPay Documentation

# Embedded widget

Integrating via the XanPay widget is an easy way to accept payments on your websites using a pre-built XanPay interface.

Here is a demo of what XanPay's widget could look like, with the default configuration.

# Create widget

In the dashboard (opens new window), select the look and feel that fits best with your platform. When you click on Generate widget, the code for the widget is generated. You can copy this code and inject it into your website.

# Integrate widget

The example below demonstrates how the code needs to be integrated.

<!-- Create a div container with id "xanpay-widget". -->
<div style="display: flex; justify-content: center" id="xanpay-widget"></div>
<!-- Load the XanPay widget library "1.widget.js". -->
<script src="https://cdn.xanpay.com/widget/1.widget.js"></script> 
<script>
	// Configure the widget options in an object
	const widgetOptions = {
		apiKey: "<api key>",
		currency: "SGD",
		amount: 35,
	};
	
	// Create a function _hw to load the script "widget.js"
	(function (w, d, s, o, f, js, fjs) {
		w[o] =
			w[o] ||
			function () {
				(w[o].q = w[o].q || []).push(arguments);
			};
		(js = d.createElement(s)), (fjs = d.getElementsByTagName(s)[0]);
		js.id = o;
		js.src = f;
		is.async = 0;
		fjs.parentNode.insertBefore(js, fjs);
	})(
		window,
		document,
		"script",
		"_hw",
		"https://cdn.xanpay.com/widget/widget.js"
	);
	
	// Run the function to inject the widget
	_hw("init", widgetOptions);
</script>

# Run widget

You can run the widget on your 'localhost' for development. Please note: replace '127.0.0.1' in your URL with localhost.

When you are ready to deploy on your domain, go to Domain configuration (opens new window) and add domains. This needs to be approved by XanPay before it is operational.

# Configuration options

Once the widget is working on your page, you can consider customising it further based on your needs. The widget constructor accepts an object with the following parameters which can help you configure the widget according to your needs.

Parameter Required Description
apiKey Required A unique key identifying a partner
currency Required Currency in which you set the amount
amount Required Amount to be charged
isSandbox Optional Default is false
lang Optional English by default. Available locales
subscriptionMode Optional Default is false
subscriptionPlanId Required if subscriptionMode is true ID of the subscription plan
orders Optional A list of orders
paymentMethods Optional Permitted payment methods
notifyPayload Optional Custom data to be saved as a part of the charge object
redirectUrl Optional Enables a button that takes the customer back to the specified url
customer Optional Used to autofill some of the fields of the widget for the customer
onEvent Optional Callback function to be triggered when events such as charge creation take place. The handler accepts event and data parameters.

# Advanced configuration

Following is an example of how the widget can be customized:

<!-- Create a div container with id "xanpay-widget". -->
<div style="display: flex; justify-content: center" id="xanpay-widget"></div>
<!-- Load the XanPay widget library "1.widget.js". -->
<script src="https://cdn.xanpay.com/widget/1.widget.js"></script> 
<script>
	// Setup the widget configuration
	const customer = {
	  email: "<customer email here>",
	  firstName: "<customer first name here>",
	  lastName: "<customer last name here>",
	  phone: {
	    code: "+65",
	    phone: "12345678901",
	  },
	};
	const widgetOptions = {
	  apiKey: "<api key>",
	  currency: "SGD",
	  amount: 35,
	  customer: customer,
	  onEvent: async (event, data) => {
	    if (event === "charge_created") {
	      // code to handle data.charge object
	    }
	  },
	};
	
	// Create a function _hw to load the script "widget.js"
	(function (w, d, s, o, f, js, fjs) {
	  w[o] =
	    w[o] ||
	    function () {
	      (w[o].q = w[o].q || []).push(arguments);
	    };
	  (js = d.createElement(s)), (fjs = d.getElementsByTagName(s)[0]);
	  js.id = o;
	  js.src = f;
	  js.async = 0;
	  fjs.parentNode.insertBefore(js, fjs);
	})(
	  window,
	  document,
	  "script",
	  "_hw",
	  "https://cdn.xanpay.com/widget/widget.js"
	);
	
	// Run the function to inject the widget
	_hw("init", widgetOptions);
</script>