The Mandate Form Component is a user interface feature that enables buyers to select Direct Debit as a payment method and complete the mandate form without navigating away from the current page. This seamless integration enhances the user experience and simplifies the payment process. This document provides a step-by-step guide to implementing and customizing the Mandate Form Component in your platform.

Steps

1. Authorization

In order to load the Mandate Form UI Web-Embeds in your platform, an authorized API call is needed in your backend.

Generate UI components access token

`curl -X POST "https://sandbox.unipaas.com/platform/authorize"
2  -H  "accept: application/json"
3  -H  "Authorization: Bearer <PLATFORM_SECRET_KEY>"
4  -H  "Content-Type: application/json"
5  --data-raw '{
6      "scopes": ["direct_debit_read","direct_debit_write"],
7      "vendorId": "{vendorId}"
8   }'`

const request = require("request");
const url = "https://sandbox.unipaas.com/platform/authorize";
const secretKey = "<PLATFORM_SECRET_KEY>";
const vendorId = "<YOUR_VENDOR_ID>"; 
const scopes = ["consumer_public_access"]

const options = {
    url,
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Authorization": `Bearer ${secretKey}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        scopes,
        vendorId
    })
};

request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});


Verb	`POST`
Environment	`sandbox`
URL	`https://sandbox.unipaas.com/platform/authorize`

Name	Type	Required	Description
`scopes`	string	YES	The scopes`direct_debit_read` and `direct_debit_write` included in this API request example, determine the level of access required to perform specific actions, similar to `GET` and `POST` methods
`vendorId`	string	YES	A vendor ID is a unique identifier for the vendor requesting API access. You can obtain a vendor ID when you create a vendor on your platform Note! If you don't have a vendor ID, do not include the parameter in your API request, then a public access token will be issued

Response example

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZXMiOlsib25ib2FyZGluZ193cml0ZSIsInBheW91dF93cml0ZSIsImxpbmtfd3JpdGUiLCJvbmJvYXJkaW5nX3dyaXRlIiwibm90aWZpY2F0aW9uX3dyaXRlIiwiY29uZmlnX3JlYWQiLCJkaXJlY3RfZGViaXRfd3JpdGUiLCJld2FsbGV0X3JlYWQiLCJwdWJsaWNfY29uZmlnX3JlYWQiLCJsaW5rX3JlYWQiLCJvbmJvYXJkaW5nX3JlYWQiLCJub3RpZmljYXRpb25fcmVhZCIsImNvbmZpZ19yZWFkIl0sInZlbmRvcklkIjoiNjNkN2E2Njk4NGFkZDc5YWU2YmFmZDg3IiwibWVyY2hhbnRJZCI6IjYxZTZlOTdmZjEyNDJiODIwYzlkNWM4MSIsImVudiI6ImRldiIsImlhdCI6MTY4MTg1MTQ5MCwiZXhwIjoxNjgxODUzMjkwfQ.q5dCR3zfuEWCTG8HdvfEtlY7BmHxvJL0PFinlJSe8uQ",
  "expiresIn": 86400,
    "scopes": [
    "direct_debit_read","direct_debit_write"
  ],
  "vendorId": "63d7a66984add79ae6bafd87",
  "merchantId": "61e6e97ff1242b820c9d5c81",
  "env": "sandbox"
}

Name	Type	Description
`accessToken`	string	Access token for the UI Web-Embeds
`expiresIn`	string	Time until the access token expires (in seconds)
`scopes`	string	List of permissions granted for the access token
`vendorId`	string	Unique identifier for the vendor requesting access
`merchantId`	string	Unique identifier for the platform associated with the vendor
`env`	string	The environment in which the access token was issued

📘
This access token is valid for one hour, and it will be automatically refreshed whenever a UI Web-Embed communicates with the UNIPaaS servers.

Scopes

Name	Description
`direct_debit_read`	Grants all `GET` permissions required for the Mandate Form Embedded UI requests
direct_debit_write	Grants all `POST` permissions required for the Mandate Form Embedded UI requests

2.Implementation Details

The Mandate Form Component UI Web-Embed should be implemented as part of the buyer's portal. This is typically the page where users can choose to add a payment method and are expected to see the "Set up Direct Debit" call-to-action button.

When a buyer selects Direct Debit, they can complete the mandate form directly within the same interface without requiring any additional action from the platform. This allows users to quickly and easily set up their Direct Debit. After successfully setting up the mandate, the form will provide a confirmation within the same page.

3.Customer Experience

Provide users with a seamless transition from the area hosted by your platform to the mandate setup process within the same page. Customizable themes ensure that the UI Web-Embeds align with your platform's branding, delivering a consistent and smooth user experience.

4.Installation

Scopes

Start with placing the following script tag element inside of the <head> of your HTML page:

<script type="application/javascript" src="https://cdn.unipaas.com/embedded-ui.js"></script>

This script tag loads the JavaScript code that provides the functionality for implementing UNIPaaS UI Web-Embeds on a webpage. When the script is loaded and executed, it will create an object in the memory that contains methods for instantiating and interacting with the UI Web-Embeds.

General configuration

Place the following script tag element below the closing </body> tag of your HTML page.
This script is used to initialize and configure UNIPaaS UI Web-Embeds on a web page.

<script type="text/javascript">
  const config_general = {
    paymentsEnabled: true,
    theme: { 
        colors: { 
            primaryColor: "#2F80ED", 
            secondaryColor: "#687B97", 
            accentTextColor: "#2F80ED", 
            primaryButtonColor: "#2F80ED" 
        },
        fontFamily: "inherit",
        boxShadow: "0px 3px 15px rgba(27, 79, 162, 0.11)" 
    }
  }
    const components = unipaas.components("<accessToken>", config_general);
</script>

Name	Type	Required	Description
`paymentsEnabled`	boolean	YES	Indicates whether the UNIPaaS-powered embedded payments are enabled as the default payment provider for the vendor associated with the API request If set to `true`, it means that the UNIPaaS-powered embedded payments are available for use If set to `false`, it means that the vendor has chosen another payment provider/no online payments as a default option

Theme

Theme customisation allows to match the visual design of the components with your product.

Name	Type	Description
`colors.primaryColor`	string	Represents the primary color used for UI Web-Embeds
`colors.secondaryColor`	string	Represents the secondary color used for UI Web-Embeds
`colors.accentTextColor`	string	Represents the font color used for headers of UI Web-Embeds
`colors.primaryButtonColor`	string	Represents the font color used for primary buttons of UI Web-Embeds
`fontFamily`	string	Represents the font family used for UI Web-Embeds Please use `inherit` to align the font family to the one used in your platform
`boxShadow`	string	Represents the box shadow applied to UI Web-Embeds, used to create a shadow effect

Create a container

Place the following script tag element below the closing </body> tag of your HTML page.
Make sure to assign a unique ID to the container so that it can be easily identified and accessed.

<div id="mandateFormContainer"/>

Create and mount an instance below the container

Create an instance of the mandate form component and mount it to the container DOM node in your page. This should be done after the previous div has finished loading..

<script type="text/javascript">
  const mandateForm = components.create("mandate", {
   "consumerId": "668664593dae749ebdc3ec59", // replace with actual consumer ID
    "theme": {
      "colors": {
        "primaryColor": "#000000" // primary button color
      }
    }
  });
  mandateForm.mount("#mandateFormContainer");
</script>

Example: The embedded mandate form appears in a modal window

Theme

To match the visual design of the UI Web-Embeds with your platform branding, you can customize the primary color.

Name	Type	Description
`colors.primaryColor`	string	Represents the primary color used for UI Web-Embeds

5. DOM Event Listeners

The UI web-embeds generate DOM events to provide real-time updates on user activity and checkout status. These events can be used to trigger custom actions and ensure a seamless user experience on the platform's end.

Create DOM event listeners

Place the following script tag element at the very bottom, below the closing </body> tag of your HTML page.

components.on("mandateSubmit", (e) => {
    console.log("mandateSubmit", e.detail);
});
components.on("mandateSuccess", (e) => {
    console.log("mandateSuccess", e.detail);
});
components.on("mandateError", (e) => {
    console.log("mandateError", e.detail);
});

Handle DOM events

Event	Description	Action
`mandateSubmit`	Triggered when the user attempts to make a mandate submission by pressing the "Set up Direct Debit" button.	Custom action on submit
`mandateSuccess`	Triggered when a user successfully submits the mandate. Provides real-time information to the platform indicating that the mandate has been successfully processed.	Custom action on success
`mandateError`	Triggered when an error occurs during the mandate submission.	Custom action on error