HTML + JavaScript

The following document describes in detail how to integrate the Web SDK into any existing web application, no matter how it's built. With just a few lines of code you can become transactional immediately.

Loading the Web SDK

The Web SDK is loaded from your own trustshare domain. You simply have to inject the following <script/> tag into the <head/> of your website.

<!-- replace "demo" with your verified subdomain -->
<script src="https://demo.trustshare.co/sdk.js" async defer></script>

Using the Web SDK

Once the HTML above is successfully added to your <head/> element, the Web SDK should be available to use as the result of a user interaction such as a button or link click.

Modal vs. Popup vs. Iframe

We currently recommend the use of the trustshare.{...}.modal(...) method when instantiating a flow, however, you can opt to use the trustshare.{...}.popup(...) format instead. They both offer the same interface, so all parameters remain the same.

If you would rather embed the flow directly in your site, we also offer an interface for instantiating an iframe. For this, you can use the trustshare.{...}.iframe(...) format. When integrating in this manner, the user will be guided through their journey seamlessly, inside the iframe.

note

When using either a popup or a modal, trustshare is able to report on each stage of the journey using the onClose callback in case the user drops out of the journey early. With iframes, this is less granular and we can only report success upon the completion of the entire journey, as the iframe is embedded in the facilitator website and remains open.

warning

In some cases, due to the nature of the web, some constrained security sandboxes will not work with the modal and iframe formats. Where we can reliably detect this issue, we will transparently fallback to the popup format for the user.

Checkout

Modal and popup

The following examples assume that a button with a class of checkout is available within the DOM.

<button class="checkout">Checkout</button>

You are free to display this button however you want and design it accordingly. Simply add the following JavaScript to have a modal checkout process open when the button is interacted with. A full list of parameters is provided below.

document
.querySelector('.checkout')
.addEventListener('click', () => {
trustshare.checkout.modal({
to: 'seller@example.com',
from: 'buyer@example.com',
amount: 150000,
depositAmount: 100000,
description: 'An example description',
onClose({ status, token }) {
// see `status` table below
console.log({ status, token });
}
})
})

Iframe

The following examples assume that a div with a class of checkout-wrapper is available within the DOM.

<div class="checkout-wrapper">Checkout</div>

Simply add the following JavaScript to have an iframe checkout process embedded inside the container element. A full list of parameters is provided below.

const container = document.querySelector('.checkout-wrapper');
trustshare.checkout.iframe({
container,
to: 'seller@example.com',
from: 'buyer@example.com',
amount: 150000,
depositAmount: 100000,
description: 'An example description',
onComplete: ({ status, token }) => {
// see `status` table below
console.log({ status, token });
}
})

Parameters

The following parameters can be provided at the instantiation of the checkout.

ParameterOptionalModal / Popup / IframeDefaultDescription
toyesallnoneThe email address of the "seller". If not supplied, the checkout process will open with the ability for the user to fill in the To field manually.
fromyesallnoneThe email address of the "buyer". If supplied, the checkout process will pre-fill this for the user when they are required to sign in, resulting in better UX.
amountyesallnoneThe amount in the lowest common denominator of the selected currency (eg. 150000 is equal to 1,500.00). If not supplied, the checkout process will open with the ability for the user to manually enter an Amount. If depositAmount is supplied, amount is considered to be the expected total value of the transaction. amount should be supplied and greater than depositAmount if the latter is present, otherwise depositAmount will be treated as the full amount for the transaction in a normal checkout flow using amount alone.
depositAmountyesallnoneThe depositAmount in the lowest common denominator of the selected currency (eg. 150000 is equal to 1,500.00). If supplied, amount is considered to be the expected total value of the transaction, while depositAmount will be the first payment required. If depositAmount is supplied, amount should also be present and of a greater value than the deposit, otherwise depositAmount will be treated as the full amount for the transaction in a normal checkout flow using amount alone.
descriptionyesallnoneA description of the reason for the transaction. If supplied, the description should be at least 15 characters in length and accurately convey the reason for the transaction. If not supplied, the checkout process will open with the ability for the user to manually enter an Description.
currencyyesallgbpA currency to open the transaction account in, by default gbp is selected. Available currencies: gbp, eur.
onCloseyesmodal/ popupnoneA callback function that will be called whenever the checkout process is closed, whether as the result of a payment being made or not. The function will receive an object containing the status as defined below, a token field for the transaction and a paymentToken field for the payment. In the case the checkout process is closed before an IBAN is provisioned, token and paymentToken will be null.
containernoiframenoneA reference to a DOM element that the iframe will be mounted into.
onCompleteyesiframenoneA callback function that will be called whenever the checkout process is completed. The function will receive an object containing the status as defined below, a token field for the transaction and a paymentToken field for the payment.

Being notified of the result

The modal and popup take an optional onClose callback function as described above, while the iframe takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed payment or not. The onClose or onComplete handler will receive both a token and a status, outlined below.

trustshare.checkout.modal({
to: 'seller@example.com',
onClose({ status, token }) {
// see `status` table below
console.log({ status, token });
}
})

Token

The token is the unique identifier that relates to a specific transaction. A transaction is composed of multiple payments, inbound and outbound, and also denotes the provisioning of a dedicated IBAN the "buyer" can use to manually make payments.

It is recommended to use the value of the token as the correlation between your own system and trustshare if needed. All Webhooks relating to transactions will also include the token.

note

In the case token is returned as null, no IBAN was provisioned and the process is considered void.

Payment Token

The paymentToken is the unique identifier that relates to one of multiple payments that comprises a transaction.

It is recommended to use the value of the token as the correlation between your own system and trustshare if needed. All Webhooks relating to payments will also include the paymentToken.

note

In the case paymentToken is returned as null, either the checkout process has been terminated without any payment action from the user, or they have chosen to settle via a manual bank transfer, indicating that a payment was made. In the case of early termination, both token and paymentToken will be null. While with an indicated manual transfer, the transaction token will be defined, but paymentToken will be returned as null still.

Status

The following statuses can be returned to the onClose callback handler. Where applicable, the value for token will be null.

StatusMeaning
checkout_not_initiatedThe checkout process was opened, however the user never continued the process. token will be null.
login_not_initiatedThe user clicked on the "Pay Now" button in the checkout flow, but did not log in to trustshare. token will be null.
second_factor_not_providedThe user clicked on the "Pay Now" button in the checkout flow, signed up or logged in, but did not verify their email with a one-time password. token will be null.
transaction_initiatedA dedicated IBAN was provisioned for the transaction however the user closed the checkout before indicating a payment was made. IBANs are reserved for 2 weeks before a transaction is considered abandoned if no payments are made into the account. token will be defined.
manual_payment_indicatedA user made their way through the complete checkout flow and indicated that they had made a manual payment into the dedicated account. token will be defined.
payment_madeA user made their way through the complete checkout flow and a payment was made into the dedicated account via Open Banking. token will be defined.

Deposit flow

For transactions where the initial payment of a deposit is required, either as part of a payment schedule or as a one off, we provide the depositAmount field for our checkout SDKs. If provided as an argument to one of the checkout method calls, we will consider amount to be the expected total value of the transaction, while depositAmount will be the first payment required. Fee calculations will be based on the indicated total value i.e. amount. If depositAmount is supplied, amount should also be present in the arguments and of a greater value than the deposit, otherwise depositAmount will be treated as the full amount for the transaction in a normal checkout flow using amount alone.

Release

Modal and popup

The following examples assume that a button with a class of release is available within the DOM.

<button class="release">Release</button>

You are free to display this button however you want and design it accordingly. Simply add the following JavaScript to have a modal release process open when the button is interacted with. A full list of parameters is provided below.

document
.querySelector('.release')
.addEventListener('click', () => {
trustshare.release.modal({
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onClose({ status, token, paymentToken, amount }) {
// see `status` table below
console.log({ status, token, paymentToken, amount });
}
})
})

Iframe

The following examples assume that a div with a class of release-wrapper is available within the DOM.

<div class="release-wrapper">Release</div>

Simply add the following JavaScript to have an iframe release process embedded inside the container element. A full list of parameters is provided below.

const container = document.querySelector('.release-wrapper');
trustshare.release.iframe({
container,
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onComplete: ({ status, token }) => {
// see `status` table below
console.log({ status, token });
}
})

Parameters

The following parameters can be provided at the instantiation of the release.

ParameterOptionalModal / Popup / IframeDefaultDescription
tokennoallnoneThe transaction token. A token must be provided in the call to the modal or popup function
amountyesallnoneThe amount in the lowest common denominator of the selected currency (eg. 150000 is equal to 1,500.00). If not supplied, the release funds process will open with the ability for the user to manually enter an Amount.
onCloseyesmodal/ popupnoneA callback function that will be called whenever the release process is closed, whether as the result of a payment being made or not. The function will receive an object containing the status as defined below, a token field for the transaction, a paymentToken field for the payment and an amount field denoting the amount of money released. In the case the release process is closed before completion paymentToken will be null.
containernoiframenoneA reference to a DOM element that the iframe will be mounted into.
onCompleteyesiframenoneA callback function that will be called whenever the release process is completed. The function will receive an object containing the status as defined below, a token field for the transaction, a paymentToken field for the payment and an amount field denoting the amount of money released.

Being notified of the result

The modal and popup take an optional onClose callback function as described above, while the iframe takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed release or not. The onClose or onComplete handler will receive both a token and a status, outlined below.

trustshare.release.modal({
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onClose({ status, token, paymentToken, amount }) {
// see `status` table below
console.log({ status, token, paymentToken, amount });
}
})

Payment Token

The paymentToken is the unique identifier that relates to one of multiple payments that comprises a transaction.

It is recommended to use the value of the token as the correlation between your own system and trustshare if needed. All Webhooks relating to payments will also include the paymentToken.

note

In the case paymentToken is returned as null, no release was made and the process is considered void.

Status

The following statuses can be returned to the onClose callback handler. Where applicable, the value for paymentToken will be null.

StatusMeaning
release_not_initiatedThe release process was opened, however the user never continued the process. paymentToken will be null.
login_not_initiatedThe user initiated the release funds flow, but did not log in to trustshare. paymentToken will be null.
second_factor_not_providedThe user initiated the release funds flow, signed up or logged in, but did not verify their email with a one-time password. paymentToken will be null.
release_madeA user made their way through the complete release flow and a payment was made to the nominated account. At this point the specified amount of money is no longer in escrow. paymentToken will be defined.

Return

Modal and popup

The following examples assume that a button with a class of return is available within the DOM.

<button class="return">Return</button>

You are free to display this button however you want and design it accordingly. Simply add the following JavaScript to have a modal return process open when the button is interacted with. A full list of parameters is provided below.

document
.querySelector('.return')
.addEventListener('click', () => {
trustshare.return.modal({
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onClose({ status, token, paymentToken, amount }) {
// see `status` table below
console.log({ status, token, paymentToken, amount });
}
})
})

Iframe

The following examples assume that a div with a class of return-wrapper is available within the DOM.

<div class="return-wrapper">Return</div>

Simply add the following JavaScript to have an iframe return process embedded inside the container element. A full list of parameters is provided below.

const container = document.querySelector('.return-wrapper');
trustshare.return.iframe({
container,
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onComplete: ({ status, token }) => {
// see `status` table below
console.log({ status, token });
}
})

Parameters

The following parameters can be provided at the instantiation of the return.

ParameterOptionalModal / Popup / IframeDefaultDescription
tokennoallnoneThe transaction token. A token must be provided in the call to the modal or popup function
amountyesallnoneThe amount in the lowest common denominator of the selected currency (eg. 150000 is equal to 1,500.00). If not supplied, the return funds process will open with the ability for the user to manually enter an Amount.
onCloseyesmodal/ popupnoneA callback function that will be called whenever the return process is closed, whether as the result of a payment being made or not. The function will receive an object containing the status as defined below, a token field for the transaction, a paymentToken field for the payment and an amount field denoting the amount of money returned. In the case the return process is closed before completion paymentToken will be null.
containernoiframenoneA reference to a DOM element that the iframe will be mounted into.
onCompleteyesiframenoneA callback function that will be called whenever the return process is completed. The function will receive an object containing the status as defined below, a token field for the transaction, a paymentToken field for the payment and an amount field denoting the amount of money returned.

Being notified of the result

The modal and popup take an optional onClose callback function as described above, while the iframe takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed return or not. The onClose or onComplete handler will receive both a token and a status, outlined below.

trustshare.return.modal({
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onClose({ status, token, paymentToken, amount }) {
// see `status` table below
console.log({ status, token, paymentToken, amount });
}
})

Payment Token

The paymentToken is the unique identifier that relates to one of multiple payments that comprises a transaction.

It is recommended to use the value of the token as the correlation between your own system and trustshare if needed. All Webhooks relating to payments will also include the paymentToken.

note

In the case paymentToken is returned as null, no return was made and the process is considered void.

Status

The following statuses can be returned to the onClose callback handler. Where applicable, the value for paymentToken will be null.

StatusMeaning
return_not_initiatedThe return process was opened, however the user never continued the process. paymentToken will be null.
login_not_initiatedThe user initiated the return funds flow, but did not log in to trustshare. paymentToken will be null.
second_factor_not_providedThe user initiated the return funds flow, signed up or logged in, but did not verify their email with a one-time password. paymentToken will be null.
return_madeA user made their way through the complete return flow and a payment was made to the nominated account. At this point the specified amount of money is no longer in escrow. paymentToken will be defined.

Topup

Modal and popup

The following examples assume that a button with a class of topup is available within the DOM.

<button class="topup">Topup</button>

You are free to display this button however you want and design it accordingly. Simply add the following JavaScript to have a modal topup process open when the button is interacted with. A full list of parameters is provided below.

document
.querySelector('.topup')
.addEventListener('click', () => {
trustshare.topup.modal({
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onClose({ status, token, paymentToken, amount }) {
// see `status` table below
console.log({ status, token, paymentToken, amount });
}
})
})

Iframe

The following examples assume that a div with a class of topup-wrapper is available within the DOM.

<div class="topup-wrapper">Topup</div>

Simply add the following JavaScript to have an iframe topup process embedded inside the container element. A full list of parameters is provided below.

const container = document.querySelector('.topup-wrapper');
trustshare.topup.iframe({
container,
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onComplete: ({ status, token }) => {
// see `status` table below
console.log({ status, token });
}
})

Parameters

The following parameters can be provided at the instantiation of the topup.

ParameterOptionalModal / Popup / IframeDefaultDescription
tokennoallnoneThe transaction token. A token must be provided in the call to the modal or popup function
amountyesallnoneThe amount in the lowest common denominator of the selected currency (eg. 150000 is equal to 1,500.00). If not supplied, the topup funds process will open with the ability for the user to manually enter an Amount.
onCloseyesmodal/ popupnoneA callback function that will be called whenever the topup process is closed, whether as the result of a payment being made or not. The function will receive an object containing the status as defined below, a token field for the transaction, a paymentToken field for the payment and an amount field denoting the amount of money paid in. In the case the topup process is closed before completion paymentToken will be null.
containernoiframenoneA reference to a DOM element that the iframe will be mounted into.
onCompleteyesiframenoneA callback function that will be called whenever the topup process is completed. The function will receive an object containing the status as defined below, a token field for the transaction, a paymentToken field for the payment and an amount field denoting the amount of money paid in.

Being notified of the result

The modal and popup take an optional onClose callback function as described above, while the iframe takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed payment or not. The onClose or onComplete handler will receive both a token and a status, outlined below.

trustshare.topup.modal({
token: 'cIe58WCUo6L4gx0B',
amount: 1500,
onClose({ status, token, paymentToken, amount }) {
// see `status` table below
console.log({ status, token, paymentToken, amount });
}
})

Payment Token

The paymentToken is the unique identifier that relates to one of multiple payments that comprises a transaction.

It is recommended to use the value of the token as the correlation between your own system and trustshare if needed. All Webhooks relating to payments will also include the paymentToken.

note

In the case paymentToken is returned as null, either the topup process has been terminated without any payment action from the user, or they have chosen to settle via a manual bank transfer, indicating that a payment was made. In the case of early termination, both token and paymentToken will be null. While with an indicated manual transfer, the transaction token will be defined, but paymentToken will be returned as null still.

Status

The following statuses can be returned to the onClose callback handler. Where applicable, the value for paymentToken will be null.

StatusMeaning
topup_not_initiatedThe topup process was opened, however the user never continued the process. paymentToken will be null.
login_not_initiatedThe user initiated the topup flow, but did not log in to trustshare. paymentToken will be null.
second_factor_not_providedThe user initiated the topup flow, signed up or logged in, but did not verify their email with a one-time password. paymentToken will be null.
manual_payment_indicatedA user made their way through the complete topup flow and indicated that they had made a manual payment into the dedicated account. token will be defined and paymentToken will be null.
payment_madeA user made their way through the complete topup flow and a payment was made to the nominated account. At this point the specified amount of money is now in escrow. paymentToken will be defined.

Dispute

Modal and popup

The following examples assume that a button with a class of dispute is available within the DOM.

<button class="dispute">Dispute</button>

You are free to display this button however you want and design it accordingly. Simply add the following JavaScript to have a modal dispute process open when the button is interacted with. A full list of parameters is provided below.

document
.querySelector('.dispute')
.addEventListener('click', () => {
trustshare.dispute.modal({
token: 'cIe58WCUo6L4gx0B',
onClose({ status, token, reason }) {
// see `status` table below
console.log({ status, token, reason });
}
})
})

Iframe

The following examples assume that a div with a class of dispute-wrapper is available within the DOM.

<div class="dispute-wrapper">Dispute</div>

Simply add the following JavaScript to have an iframe dispute process embedded inside the container element. A full list of parameters is provided below.

const container = document.querySelector('.dispute-wrapper');
trustshare.dispute.iframe({
container,
token: 'cIe58WCUo6L4gx0B',
onComplete: ({ status, token, reason }) => {
// see `status` table below
console.log({ status, token, reason });
}
})

Parameters

The following parameters can be provided at the instantiation of the dispute.

ParameterOptionalModal / Popup / IframeDefaultDescription
tokennoallnoneThe transaction token. A token must be provided in the call to the modal or popup function
onCloseyesmodal/ popupnoneA callback function that will be called whenever the dispute process is closed, whether as the result of a dispute being made or not. The function will receive an object containing the status as defined below, a token field for the transaction, and a reason field for the reason the dispute is being made.
containernoiframenoneA reference to a DOM element that the iframe will be mounted into.
onCompleteyesiframenoneA callback function that will be called whenever the dispute process is completed. The function will receive an object containing the status as defined below, a token field for the transaction, and a reason field for the reason the dispute is being made.

Being notified of the result

The modal and popup take an optional onClose callback function as described above, while the iframe takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed dispute or not. The onClose or onComplete handler will receive both a token and a status, and an option reason outlined below.

trustshare.dispute.modal({
token: 'cIe58WCUo6L4gx0B',
onClose({ status, token, reason }) {
// see `status` table below
console.log({ status, token, reason });
}
})

Token

The token is the unique identifier that relates to a specific transaction.

It is recommended to use the value of the token as the correlation between your own system and trustshare if needed. All Webhooks relating to transactions will also include the token.

Reason

The reason is the reason given for the dispute process. Currently, these values can be either seller_unresponsive or other. If the dispute flow is initiated but not completed, the reason will be null.

Status

The following statuses can be returned to the onClose callback handler.

StatusMeaning
dispute_not_initiatedThe dispute process was opened, however the user never continued the process.
login_not_initiatedThe user initiated the dispute flow, but did not log in to trustshare.
second_factor_not_providedThe user initiated the dispute flow, signed up or logged in, but did not verify their email with a one-time password.
dispute_raisedA user completed the dispute flow. At this point the transaction is effectively paused and no actions can be taken by either party until the dispute has been resolved.