Integration Guide for Payment Widget

You can read basic information about the payment widget here: Payment Widget.

Base URLs

You can use Payment Widget both for Invoices and Channels. Use the following URLs to generate links for an invoice or channel:

Type	URL
Invoice	https://sandbox-payment-widget.munzen.io/invoice?[params]
Channel	https://sandbox-payment-widget.munzen.io/channel?[params]

Params for Initialisation

You can set the following params for the Payment Widget to add custom information about customer, order, etc:

{
  customer_external_id: string;
  external_id: string;
  external_data: Record<string, string>;
  description: string;
  name: string;
	
  // Theme is a purely presentational parameter, not used in signature generation
  // It has 2 options, "dark" or "light" -
  // Choose what better suits your application look & feel
  theme: 'dark' | 'light';
};

Here is the only required param: customer_external_id. All other parameters are optional, you can ignore them if you want.

Here is an example of defined params:

const parameters = {
    customer_external_id: '[email protected]',
    external_id: 'invoice_1',
    external_data: { "game_id": "1" },
    name: "Invoice #1 from site.com",
    description: "Invoice payment from the main page",
}

When you build your params then you need to generate a signature.

Generate Signature

We need a signature to validate that you can use the widget to accept customer payments. Here is an example of signature generation:

JS Example Code

const crypto = require('crypto');

// You should never expose this key to client code (front-end).
// Make sure to generate signatures only on the back-end
const SECRET_KEY = 'PUT_YOUR_API_SECRET_HERE'

const values = {
    theme: 'light', // or 'dark'
    customer_external_id: '[email protected]',
    external_id: 'invoice_1',
    external_data: { "game_id": "1" },
    name: "Invoice #1 from site.com",
    description: "Invoice payment from the main page",
}

const signature = getSignature({
  timestamp: 1684241941,
  customer_external_id: values.customer_external_id,
  external_id: values.external_id,
  external_data: JSON.stringify(values.external_data),
  description: values.description,
  name: values.name,
}).then(signature => console.log(signature));

async function getSignature(data) {
  const sortedData = ksortRecursive({ ...data });
  const string = implodeRecursive(sortedData);
  const message = `POST` + string;
  
  console.log(message);
  const signature = hmacSha256(message, SECRET_KEY);

  return signature;
}

async function hmacSha256(data, secret) {
  const hash = crypto.createHmac("sha-256", secret).update(data).digest('hex');

  return hash;
}

function ksortRecursive(obj) {
  if (!Array.isArray(obj) && typeof obj !== 'object') {
    return obj;
  }
  const sortedObj = {};

  Object.keys(obj)
    .sort()
    .forEach((key) => {
      const value = obj[key];
      sortedObj[key] = ksortRecursive(value);
    });
  return sortedObj;
}

function implodeRecursive(arr) {
  if (!Array.isArray(arr) && typeof arr !== 'object') {
    throw new Error('implodeRecursive: argument must be an array or object');
  }

  let output = '';
  Object.keys(arr).forEach((key) => {
    const item = arr[key];
    if (Array.isArray(item)) {
      output += implodeRecursive(item);
    } else {
      output += item;
    }
  });
  return output;
}

Generate Widget Link

Let's generate query params for the Payment Widget URL:

const params = {
  signature: signature,
  timestamp: timestamp,
  customer_external_id: encodeURIComponent(
    values.customer_external_id
  ),
  theme: values.theme,
  external_id: encodeURIComponent(values.external_id),
  external_data: JSON.stringify(values.external_data),
  description: encodeURIComponent(values.description),
  name: encodeURIComponent(values.name),
}

const widgetUrlParams = new URLSearchParams(params);
const queryString = widgetUrlParams.toString();

// Example usage with URL
const url = new URL('https://sandbox-payment-widget.munzen.io/invoice');
url.search = queryString;

console.log(url.toString());

You will receive a full URL to the Payment Widget. It will look like this:

https://sandbox-payment-widget.munzen.io/invoice?signature=8cb2dd83f06ff3dcbf61d501e5fb512e3d5343ffc6823651097739e23a0475ce&timestamp=1684241941&customer_external_id=johnny%2540email.com&theme=light&external_id=invoice_1&external_data=%7B%22game_id%22%3A%221%22%7D&description=Invoice%2520payment%2520from%2520the%2520main%2520page&name=Invoice%2520%25231%2520from%2520site.com

Show Widget to the Customer

Now you have an URL for the payment widget. You can redirect the customer to this URL or open this URL inside an iframe.