API Reference

borderless™ Link™ - Quick Start

In This Section

In the borderless™ Link™ section of the borderless™ documentation you will find:

  • borderless™ Link™ Overview
  • How to Integrate borderless™ Link™
  • borderless™ Link™ Responses
  • borderless™ Link™ Product Shots

borderless™ Link™ Overview

🚧

Deprecation warning!

In order to enhance security of borderless™ Link™, identifying widget with JWT token will be deprecated. New identification will have to be retrieved through a dedicated endpoint. The obtained widgetId, serving as the unique identifier, will subsequently be utilized in constructing the widget URL.

During the transition period, both authentication methods will work but we strongly advise you to switch over to new and enhanced method.

Embed the /externalContacts endpoint directly into your application with borderless™ Link™. With borderless™ Link™, recipients follow the instructions on the Widget to add their data. borderless™ Link™ automatically configures and collects the data requirements for all borderless™ supported countries. Once a user inputs their information, borderless™ will create a unique and auto-generated @handle for API payouts (example: "@^28291AS"). To learn more about borderless™ @handles please visit @Handle Overview.

Integrating borderless™ Link™

Follow these steps to integrate borderless™ Link™ on your application.

Step 1: Create Page

Create the page that the widget will be integrated into.

Step 2: Integrate iframe

Create a div element with an iframe element nested inside it.

<div>
    <iframe/>
</div>

Step 3: Add URL

Add the appropriate url in the "src" attribute of the iframe element.

👍

Pro Tip

When generating the url, you must ensure that the correct widget identifier is included.

Use the following format: 

<iframe src="https://secure.getborderless.com/widgets/add-external-contact?widgetId={unique widget identifier}" />

<iframe src="https://secure.getborderless.com/widgets/add-external-contact?token={your JWT token here}" />

Example url:
https://secure.getborderless.com/widgets/add-external-contact?widgetId=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJhwNDA5bnQwMDHo5d3NubTZhIiwiaWF0IjoxNjQyNzg2ODk2fQ=

👍

Pro Tip

To launch the Widget in Sandbox please use the following URL format: 

   <iframe src="https://sandbox.secure.getborderless.com/widgets/add-external-contact?widgetId={unique widget identifier}" />

   <iframe src="https://sandbox.secure.getborderless.com/widgets/add-external-contact?token={your JWT token here}" />

Step 4: Pass Contact Data to the Widget (Optional)

If you already have collected some information about the contact you can pass that data in the widget URL In addition to the widget identifier. Additional parameters are connected with "&" sign and the name of the parameters are equivalent as in POST /externalContact body (you can read more about external contact required information and contact creation in External Contacts Recipes section).

Information that is passed via Widget URL is gonna be pre-filled in the widget itself. 

<iframe src="https://secure.getborderless.com/widgets/add-external-contact?widgetId={your widget id}&firstName=Dalia&accountType=PERSONAL&currency=USD" />

Step 5: Customize Widget (Optional)

Add title, height, and width specifications to the Widget.

<div>
    <iframe title="widget" width="600px" height="900px" src="https://secure.getborderless.com/widgets/add-external-contact?widgetId={your widget id}" />
</div>

<div>
    <iframe title="widget" width="600px" height="900px" src="https://secure.getborderless.com/widgets/add-external-contact?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3N1ZXIiOiJja3hwNDA5bnQwMDc2MDk3OHo5d3NubTZhIiwiaWF0IjoxNjQyNzg2ODk2fQ.iAPLNOUwQICuHH4cFhcF8CSmYvW0BDMGlUFYyTnSn8s" />
</div>

👍

Pro Tip

The borderless™ Widget is designed to dynamically adjust the data requirements based on Country and Account Type. Required fields can be found at the /externalContact/requiredInformation endpoint.

Customization Options

Depending on your API package you can customize the look and feel of your Widget from the Developer tab of your borderless™ Dashboard, including these options.

ItemCustomization
textColorChange the colors for the inputs on the widget's preview card.
buttonCopyColorChange the colors of the button's copy.
mainColorChange the color of the widget's buttons.
backgroundColorChange the background of the preview card.
fontFamilyChange the font of the text displayed on the widget.

Widget Responses

When a user submits their information through the Widget, the borderless™ API will provide a response. Responses are sent via postMessage (Click here to learn more about postMessage. To access the response data you will need an eventListener to listen for incoming messages.

There are two types of responses you may receive:

  1. Success (Status of "Pending" or "Approved")
  2. Error

Successful Contact Creation

When a user successfully submits their information through the Widget, the Contact status will be sent to your application via postMessage.

window.addEventListener('message', e => {
    console.log(e.data) // { externalContactId: ^xxxxx, status: “APPROVED” }
});

Error

When a user is unsuccessful in submitting their information through the Widget, an Error message will be displayed to the user and also sent to your application via postMessage. 

window.addEventListener('message', e => {
    console.log(e.data) // { message: “Sorry, this email is already associated with an account. Please pay them using their handle: @{contactSlug} (I-6303)” }
});

Widget Product Shots

For Widget product shots please refer to the borderless™ Link™ Widget Overview.