EPP to Web SDK migration guide

The Web SDK is our latest and most feature-rich UI, designed to maximise conversion. It includes features such as:

• payment retries, which enable you to attempt a failed payment again
• a flow for returning users, which simplifies the end-user experience even further using saved account details
• the TrueLayer Pay button, which contains the most relevant banks to them based on the banks they've used previously, or the most used banks in their market.

We recommend that you migrate to the Web SDK for the best user experience in the countries that offer it. In countries that the Web SDK doesn’t support yet, users will see the embedded payment page (EPP) UI.

📘

The web SDK is available in the UK, France (FR) and Germany (DE).

More countries are coming soon.

Here’s how to migrate from the embedded payment page to the Web SDK:

1. Migrate from the EPP to the Web SDK library

Install the new webSDK npm package (truelayer-web-sdk), and remove the EPP package (truelayer-embedded-payment-page):

npm i truelayer-web-sdk

npm uninstall truelayer-embedded-payment-page

---

yarn add truelayer-web-sdk

yarn remove truelayer-embedded-payment-page

---

pnpm install truelayer-web-sdk

pnpm uninstall truelayer-embedded-payment-page

Configure the Pay button

The TrueLayer Pay button is a UI feature that is unique to the Web SDK. This button:

• initialises the payment dialog
• enables your returning users to select from any saved bank accounts at the beginning of the payment flow.

When a user clicks the Pay button, they initiate a payment and the payment flow begins.

To learn more about the Pay button, go to the Web SDK docs.

2. (UK only) Configure retries in your payment requests

Retries

If you are integrating the Web SDK in the UK, add an empty retry object to your Create Payment requests. If you are not in the UK, skip this step.

{
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": [
          "GB"
        ],
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ]
      },
      "scheme_selection": {
        "type": "instant_preferred",
        "allow_remitter_fee": false
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "verification": {
        "type": "automated"
      },
      "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
      "account_holder_name": "Ben Eficiary",
      "reference": "payment-ref",
      "statement_reference": "payment-ref"
    },
    "retry": {}
  },
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
    "name": "Remi Terr",
    "email": "remi.terr@aol.com",
    "phone": "+447777777777",
    "date_of_birth": "1990-01-31"
  },
  "sub_merchants": {
    "ultimate_counterparty": {
      "type": "business_division"
    }
  }
}
'

3. Mandatory properties for Web SDK

When you make a payment with the Web SDK in any geography, you must also pass:

• your client ID, in the clientId field
• your end user’s email address, inside the user object

const { start, mount } = initWebSdk({
  hostedResultScreen: {
    returnUri: 'https://example.org/return-page'
  },
  ...
})

// mount the Pay button (stays in a loading state until `start(...)` is called)
mount(document.getElementById('your-container-id'))

// pass the `paymentId` and `resourceToken` to enable the Pay button
start({ paymentId, resourceToken })

3.1. Provider filters

You must apply a provider filter that prevents the user from selecting a country in which the web SDK is not supported. It’s easiest to restrict the payment to the country that you’re based in. Without this country restriction, the EPP flow will be used everywhere and your user will not see the web SDK flow.

You can also supply provider IDs in the providerIds field to show specific banks.

{
  providerFilters: {
    countries: string[],
    providerIds: string[],
    releaseChannel: 'general_availability' | 'public_beta' | 'private_beta',
  },

4. Initialise the Web SDK and listen for Web SDK callbacks

The Web SDK has its own set of callbacks to indicate when the user reaches certain stages in the payment flow. You need to set up your integration to listen for these.

For more detailed information about callbacks, see the Web SDK docs.