Buyer UI: Embedded Mandate Form Implementation Guide

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
  2. Implementation Details
  3. Customer Experience
  4. Installation
  5. DOM EventListeners

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);
});
VerbPOST
Environmentsandbox
URLhttps://sandbox.unipaas.com/platform/authorize
NameTypeRequiredDescription
scopesstringYESThe scopesdirect_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
vendorIdstringYESA 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"
}
NameTypeDescription
accessTokenstringAccess token for the UI Web-Embeds
expiresInstringTime until the access token expires (in seconds)
scopesstringList of permissions granted for the access token
vendorIdstringUnique identifier for the vendor requesting access
merchantIdstringUnique identifier for the platform associated with the vendor
envstringThe 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

NameDescription
direct_debit_readGrants all GET permissions required for the Mandate Form Embedded UI requests
direct_debit_writeGrants 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>
NameTypeRequiredDescription
paymentsEnabledbooleanYESIndicates 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.

NameTypeDescription
colors.primaryColorstringRepresents the primary color used for UI Web-Embeds
colors.secondaryColorstringRepresents the secondary color used for UI Web-Embeds
colors.accentTextColorstringRepresents the font color used for headers of UI Web-Embeds
colors.primaryButtonColorstringRepresents the font color used for primary buttons of UI Web-Embeds
fontFamilystringRepresents the font family used for UI Web-Embeds
Please use inherit to align the font family to the one used in your platform
boxShadowstringRepresents 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.

NameTypeDescription
colors.primaryColorstringRepresents 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

EventDescriptionAction
mandateSubmitTriggered when the user attempts to make a mandate submission by pressing the "Set up Direct Debit" button.Custom action on submit
mandateSuccessTriggered 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
mandateErrorTriggered when an error occurs during the mandate submission.Custom action on error