Getting Started with the Payee Widget
This page will help you get started on using the payee widget to securely onboard your payees.
Using the Payee Widget
The Payee Widget is useful when you want to onboard users (in other words collect their information) on your own platform, application, or website. The Payee Widget is fully mobile ready so there is no need to worry about what device your payee will be using.
The requirements to compliantly transfer money to the payees and, if applicable, complete the required tax obligations are highly volatile and change frequently, often times without notice. So in order to make things simpler for you, we created the Payee Widget. This means that Payment Labs will make sure the UX is always up-to-date and ready to collect the correct information for you.
Implementation Steps
To utilize the widget you will need to call the Get Widget URL endpoint. This endpoint provide you with an embeddable URL that you can then load on an iframe.
As payees onboard you can receive webhooks to keep yourself updated to determine if the payee is payable or not. Refer to the Webhooks section of our API to learn more on how to create webhooks.
For payee payability updates, refer to the Payee Payability Changed webhook message.
Notification Handling
Sometimes the payee might be notified that their information is invalid or that additional compliance information is needed. To keep the payee experience to be as smooth as possible, we include an additional redirectPath
in the URL leading back to your application. However, in order for the payee to see the applicable section within the widget (such as a specific payment they are being linked to), it's necessary to implement the redirectPath
flow.
Whenever we need the widget to deep link to a specific section, we'll send a redirectpath
that needs to be passed on to the redirectPath
field of the Get Widget URL endpoint when generating the widget URL. This will ensure the widget loads the correction section.
Events
To allow compatibility with a fully seamless layout, the widget emits a few events that can be listened to:
PL_APP_HEIGHT
The PL_APP_HEIGHT
event is fired every time the widget content height changes. The height value is in pixels
. We recommend implementing this event so that you can also set the iframe object height to be equal to the content height. This is done to ensure there are no scrollbars on the iframe and improves the overall UX for the payee.
function iframeHeightEventHandler(e) {
const { data } = e;
if (data.id === "PL_APP_HEIGHT") {
// Set it to a custom CSS variable applied to the iframe
document.documentElement.style.setProperty("--iframe-height", `${data.height}px`);
// Or use something like local state
setIframeHeight(data.height);
}
}
window.addEventListener("message", iframeHeightEventHandler);
PL_APP_MOUNTED
The PL_APP_MOUNTED
event can be used to show your custom loading screen until the widget has initialized instead of seeing a blank white screen while the assets are downloading.
function iframeReadyEventHandler(e) {
const { data } = e;
if (data.id === "PL_APP_MOUNTED") {
// Set a flag or perform actions when iframe is mounted
console.log("iframe is ready");
// Example: setting a flag
isIframeReady = true;
}
}
window.addEventListener("message", iframeReadyEventHandler);
PL_APP_RELOAD
The PL_APP_RELOAD
is an event to support when the widget needs to reload.
function iframeReloadEventHandler(e) {
const { data } = e;
if (data.id === "PL_APP_RELOAD") {
window.location.reload();
}
}
window.addEventListener("message", iframeReloadEventHandler);
See the following guide to learn more about events in the browser: window.postMessage()
Customization
The widget can be customized to your brand's look and feel. Contact us and we can configure the available customizations for you.
Currently the following fields can be customized:
{
"colors": {
"seed": {
"brand": "226cff",
"neutral": "1f62e6",
"info": "1c57cc",
"positive": "e9f1ff",
"negative": "a7c5ff",
"warning": "6599ff"
},
"overrides": {
"bg-main": "000000"
}
}
}
Please note the above are the default values for the colors utilized on the widget.
We're also able to customize the logo shown on login screen and other places with your own logo.
Updated 8 days ago