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.