React SDK

The following document describes in detail how to integrate our SDK into your React application. In the case you are building a React application, this is the recommeded approach for integration with trustshare.

Installation

Use your preferred method to install @trustshare/react-sdk from npm.

yarn add @trustshare/react-sdk

npm install --save @trustshare/react-sdk

Hooks vs Components

There are two main ways of using our SDK in React applications. For each of the flows (checkout, release, topup, return), we provide both React components and hooks.

React components allow you to embed our iframe directly in your site. In this case no modal or popups will be created by the SDK. The user will be guided through their journey seamlessly, inside the iframe.

Hooks will provide developers with a function called open that they can use in any event handlers to kick start a trustshare journey. When implementing flows this way, the user will be taken through the journey in either a modal or a popup window.

Hooks and Components share the arguments that need to be provided at instantiation.

note

When using hooks, 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 Components, 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.

Modal vs. Popup

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

warning

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

Using `Checkout` and `useCheckout`

Import the @trustshare/react-sdk package into your application to use the Checkout component or the useCheckout hook. The hook returns a function called open which can take parameters that will override those provided when instantiating the hook. A full list of parameters is provided below.

import { Checkout } from '@trustshare/react-sdk';

function App() {
  return (
    <div className="MyWrapper">
      <Checkout
        subdomain="demo"
        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 });
        }}
      />
    </div>
  );
}

import { useCheckout } from '@trustshare/react-sdk';

function App() {
  const { open } = useCheckout({
    subdomain: 'demo',
    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 });
    }
  });

  return (
    <button onClick={() => open({ description: 'A different description' })}>
      Checkout
    </button>
  );
}

Parameters

The following parameters can be provided as props to the component or at the instantiation of the hook. Where applicable, parameters denoted as overridable can be provided to the open function.

Parameter	Optional	Overridable	Component/ Hook	Default	Description
`subdomain`	no	no	both	none	Your trustshare subdomain as chosen at sign up.
`format`	yes	no	both	`modal`	The format to display the checkout process, by default `modal` is selected. Available formats: `modal`, `popup`.
`to`	yes	yes	both	none	The 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.
`from`	yes	yes	both	none	The 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.
`amount`	yes	yes	both	none	The 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.
`depositAmount`	yes	yes	both	none	The 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.
`description`	yes	yes	both	none	A 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`.
`currency`	yes	yes	both	`gbp`	A currency to open the transaction account in, by default `gbp` is selected. Available currencies: `gbp`, `eur`.
`onClose`	yes	no	hook	none	A 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`.
`onComplete`	yes	no	component	none	A 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 React hook takes an optional onClose callback function as described above, while the component 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.

const { open } = useCheckout({
  subdomain: 'demo',
  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.

Status	Meaning
`checkout_not_initiated`	The checkout process was opened, however the user never continued the process. `token` will be `null`.
`login_not_initiated`	The 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_provided`	The 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_initiated`	A 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_indicated`	A 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_made`	A 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 the useCheckout hook, 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.

Using `Release` and `useRelease`

Import the @trustshare/react-sdk package into your application to use the Release component or the useRelease hook. The hook returns a function called open which can take parameters that will override those provided when instantiating the hook. A full list of parameters is provided below.

import { Release } from '@trustshare/react-sdk';

function App() {
  return (
    <div className="MyWrapper">
      <Release
        subdomain="demo"
        token="cIe58WCUo6L4gx0B"
        amount="150000"
        onComplete={({ status, token, paymentToken }) => {
          // see `status` table below
          console.log({ status, token, paymentToken });
        }}
      />
    </div>
  );
}

import { useRelease } from '@trustshare/react-sdk';

function App() {
  const { open } = useRelease({
    subdomain: 'demo',
    onClose({ status, amount, token, paymentToken }) {
      // see `status` table below
      console.log({ status, amount, token, paymentToken });
    }
  });

  return (
    <button onClick={() => open({ amount: 1000, token: 'cIe58WCUo6L4gx0B' })}>
      Release funds
    </button>
  );
}

Parameters

The following parameters can be provided as props to the component or at the instantiation of the hook. Where applicable, parameters denoted as overridable can be provided to the open function.

Parameter	Optional	Overridable	Component / Hook	Default	Description
`subdomain`	no	no	both	none	Your trustshare subdomain as chosen at sign up.
`format`	yes	no	both	`modal`	The format to display the release process, by default `modal` is selected. Available formats: `modal`, `popup`.
`token`	yes	yes	both	none	The transaction token. A token must be provided in either the instantiation of the hook or the `open` function
`amount`	yes	yes	both	none	The 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`.
`onClose`	yes	no	hook	none	A 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`.
`onComplete`	yes	no	component	none	A 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

const { open } = useRelease({
  subdomain: 'demo',
  token: 'cIe58WCUo6L4gx0B',
  onClose({ status, token, paymentToken, amount }) {
    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.

Status	Meaning
`release_not_initiated`	The release process was opened, however the user never continued the process. `paymentToken` will be `null`.
`login_not_initiated`	The user initiated the release funds flow, but did not log in to trustshare. `paymentToken` will be `null`.
`second_factor_not_provided`	The 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_made`	A 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.

Using `Return` and `useReturn`

Import the @trustshare/react-sdk package into your application to use the Return component or the useReturn hook. The hook returns a function called open which can take parameters that will override those provided when instantiating the hook. A full list of parameters is provided below.

import { Return } from '@trustshare/react-sdk';

function App() {
  return (
    <div className="MyWrapper">
      <Return
        subdomain="demo"
        token="cIe58WCUo6L4gx0B"
        amount="150000"
        onComplete={({ status, token, paymentToken }) => {
          // see `status` table below
          console.log({ status, token, paymentToken });
        }}
      />
    </div>
  );
}

import { useReturn } from '@trustshare/react-sdk';

function App() {
  const { open } = useReturn({
    subdomain: 'demo',
    onClose({ status, amount, token, paymentToken }) {
      // see `status` table below
      console.log({ status, amount, token, paymentToken });
    }
  });

  return (
    <button onClick={() => open({ amount: 1000, token: 'cIe58WCUo6L4gx0B' })}>
      Return funds
    </button>
  );
}

Parameters

The following parameters can be provided as props to the component or at the instantiation of the hook. Where applicable, parameters denoted as overridable can be provided to the open function.

Parameter	Optional	Overridable	Component / Hook	Default	Description
`subdomain`	no	no	both	none	Your trustshare subdomain as chosen at sign up.
`format`	yes	no	both	`modal`	The format to display the return process, by default `modal` is selected. Available formats: `modal`, `popup`.
`token`	yes	yes	both	none	The transaction token. A token must be provided in either the instantiation of the hook or the `open` function
`amount`	yes	yes	both	none	The 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`.
`onClose`	yes	no	hook	none	A 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`.
`onComplete`	yes	no	component	none	A 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 React hook takes an optional onClose callback function as described above, while the component takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed payment or not. The onClose and onComplete handler will receive an object containing keys of token, paymentToken, status and amount, outlined below.

const { open } = useReturn({
  subdomain: 'demo',
  token: 'cIe58WCUo6L4gx0B',
  onClose({ status, token, paymentToken, amount }) {
    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.

Status	Meaning
`return_not_initiated`	The return process was opened, however the user never continued the process. `paymentToken` will be `null`.
`login_not_initiated`	The user initiated the return funds flow, but did not log in to trustshare. `paymentToken` will be `null`.
`second_factor_not_provided`	The 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_made`	A 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.

Using `Topup` and `useTopup`

Import the @trustshare/react-sdk package into your application to use the Topup component or the useTopup hook. The hook returns a function called open which can take parameters that will override those provided when instantiating the hook. A full list of parameters is provided below.

import { Topup } from '@trustshare/react-sdk';

function App() {
  return (
    <div className="MyWrapper">
      <Topup
        subdomain="demo"
        token="cIe58WCUo6L4gx0B"
        amount="150000"
        onComplete={({ status, token, paymentToken }) => {
          // see `status` table below
          console.log({ status, token, paymentToken });
        }}
      />
    </div>
  );
}

import { useTopup } from '@trustshare/react-sdk';

function App() {
  const { open } = useTopup({
    subdomain: 'demo',
    onClose({ status, amount, token, paymentToken }) {
      // see `status` table below
      console.log({ status, amount, token, paymentToken });
    }
  });

  return (
    <button onClick={() => open({ amount: 1000, token: 'cIe58WCUo6L4gx0B' })}>
      Topup
    </button>
  );
}

Parameters

The following parameters can be provided as props to the component or at the instantiation of the hook. Where applicable, parameters denoted as overridable can be provided to the open function.

Parameter	Optional	Overridable	Component / Hook	Default	Description
`subdomain`	no	no	both	none	Your trustshare subdomain as chosen at sign up.
`format`	yes	no	both	`modal`	The format to display the topup process, by default `modal` is selected. Available formats: `modal`, `popup`.
`token`	yes	yes	both	none	The transaction token. A token must be provided in either the instantiation of the hook or the `open` function
`amount`	yes	yes	both	none	The 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`.
`onClose`	yes	no	hook	none	A 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`.
`onComplete`	yes	no	component	none	A 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

const { open } = useTopup({
  subdomain: 'demo',
  token: 'cIe58WCUo6L4gx0B',
  onClose({ status, token, paymentToken, amount }) {
    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.

Status	Meaning
`topup_not_initiated`	The topup process was opened, however the user never continued the process. `paymentToken` will be `null`.
`login_not_initiated`	The user initiated the topup flow, but did not log in to trustshare. `paymentToken` will be `null`.
`second_factor_not_provided`	The 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_indicated`	A 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_made`	A 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.

Using `Dispute` and `useDispute`

Import the @trustshare/react-sdk package into your application to use the Dispute component or the useDispute hook. The hook returns a function called open which can take parameters that will override those provided when instantiating the hook. A full list of parameters are provided below.

import { Dispute } from '@trustshare/react-sdk';

function App() {
  return (
    <div className="MyWrapper">
      <Dispute
        subdomain="demo"
        token="cIe58WCUo6L4gx0B"
        onComplete={({ status, token, reason }) => {
          // see `status` table below
          console.log({ status, token, reason });
        }}
      />
    </div>
  );
}

import { useDispute } from '@trustshare/react-sdk';

function App() {
  const { open } = useDispute({
    subdomain: 'demo',
    onClose({ status, token, reason }) {
      // see `status` table below
      console.log({ status, token, reason });
    }
  });

  return (
    <button onClick={() => open({ token: 'cIe58WCUo6L4gx0B' })}>
      Dispute a transaction funds
    </button>
  );
}

Parameters

The following parameters can be provided as props to the component or at the instantiation of the hook. Where applicable, parameters denoted as overridable can be provided to the open function.

Parameter	Optional	Overridable	Component / Hook	Default	Description
`subdomain`	no	no	both	none	Your trustshare subdomain as chosen at sign up.
`token`	yes	yes	both	none	The transaction token. A token must be provided in either the instantiation of the hook or the `open` function
`onClose`	yes	no	hook	none	A callback function that will be called whenever the dispute 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 `reason` as defined below.
`onComplete`	yes	no	component	none	A 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` as defined below.

Being notified of the result

The React hook takes an optional onClose callback function as described above, while the component takes onComplete. onClose will be called whenever a process is closed, whether as the result of a completed dispute or not. The onClose and onComplete handler will receive an object containing keys of token, status, reason, outlined below.

const { open } = useDispute({
  subdomain: 'demo',
  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.

Status	Meaning
`dispute_not_initiated`	The dispute process was opened, however the user never continued the process.
`login_not_initiated`	The user initiated the dispute flow, but did not log in to trustshare.
`second_factor_not_provided`	The user initiated the dispute flow, signed up or logged in, but did not verify their email with a one-time password.
`dispute_raised`	A 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.

Installation#

Hooks vs Components#

note

Modal vs. Popup#

warning

Using Checkout and useCheckout#

Parameters#

Being notified of the result#

Token#

note

Payment Token#

note

Status#

Deposit flow#

Using Release and useRelease#

Parameters#

Being notified of the result#

Payment Token#

note

Status#

Using Return and useReturn#

Parameters#

Being notified of the result#

Payment Token#

note

Status#

Using Topup and useTopup#

Parameters#

Being notified of the result#

Payment Token#

note

Status#

Using Dispute and useDispute#

Parameters#

Being notified of the result#

Token#

Reason#

Status#

Installation

Hooks vs Components

Modal vs. Popup

Using `Checkout` and `useCheckout`

Parameters

Being notified of the result

Token

Payment Token

Status

Deposit flow

Using `Release` and `useRelease`

Parameters

Being notified of the result

Payment Token

Status

Using `Return` and `useReturn`

Parameters

Being notified of the result

Payment Token

Status

Using `Topup` and `useTopup`

Parameters

Being notified of the result

Payment Token

Status

Using `Dispute` and `useDispute`

Parameters

Being notified of the result

Token

Reason

Status