# Widget integration

# Merchant dashboard widget generation

In merchant dashboard you are able to generate widget script with all necessary params and inject it into your website.

# Manual widget configuration

The following web page integrates XanPay widget into the page with base necessary configuration.

<html>
<head>
</head>
<body>
    <div style="display: flex; justify-content: center" id="xanpay-widget"></div>
</body>
<script src="https://cdn.xanpay.com/widget/1.widget.js"></script>
<script>
    (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'));
    _hw('init', {
      apiKey: '138682006413bdbf13ac7905eb0fe3c8',
      currency: 'SGD',
      amount: 355
    });
</script>
</html>

Things to note in the example:

  1. We create a div container with "xanpay-widget" id where we would like to display our widget
  2. We add XanPay widget libraries "widget.js" and "1.widget.js"
  3. We initialize the widget after the page has been loaded
  4. Here we specify only base necessary options. But widget is highly customisable - other options are described below.

# Widget options

Widget's constructor requires an option object with the following parameters.

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
subscriptionMode Optional Default is false
darkMode Optional Default is false
paymentStyles Optional list or grid. Default - list
widgetSize Optional regular - 448px, large - 650px, fit - 100% parent width.
Default - regular
orders Optional A list of orders
paymentMethods Optional An [object](#Payment methods) of payment methods
notifyUrl Optional After charge is paid this url will be notified with HTTP POST request. notifyPayload will be added to body request.
notifyPayload Optional Will be sent to notifyUrl after charge is paid
redirectUrl Optional Enables a button that takes the customer back to the specified url
hash Optional Enables the secure mode
customer Optional Can be used to autofill some of the fields of the widget for the customer

# Order object

You can provide a list of orders for each charge, they will be displayed in the final invoice and will be sent in webhook payload. About webhook and callbacks

Parameter Required Description
id Required Merchant's order id
name Required Order's name
quantity Required Quantity
amount Required Amount for the order

# Payment methods

You can specify payment methods available for each country in options. List of available payment methods might be taken from XanPay REST API.

      const paymentMethods = {
          'TH': ['prompt-pay', 'alipay-hk'],
          'HK': ['fps'],
      };

Countries and payment methods are available in XanPay API

# Secure mode

It is highly recommended using this mode, especially if your transactions are automated via webhooks.
To enable the secure mode, the hash parameter must be passed to the widget either when initializing it with SDK or with a checkout link. This hash parameter can be retrieved by performing a request on your store's backend side via our REST API before redirecting customers to payment.
Once the hash is generated, include it as a parameter to the widget, or when creating the charge via REST API.
When transactions are automated with webhooks, make sure to check that the value of the mode parameter that is contained in the signed payload is set to secure.

# Autofill

If you are redirecting customers from an online store, you may already have some of their personal information, like the email. To alleviate the need for them to enter this information twice, you can pass some or all of the fields in the following format:

const customer = {
    email: "test@test.test",
    firstName: "John",
    lastName: "Doe",
    phone: {
        code: "+66",
        phone: "12345678901"
    }
};

# Demo

Here is how our widget looks like.