Embedded Bank Payments

Embedded payments keep the bank selector inside your checkout while Trustist handles the Open Banking flow. The SDK creates the payment, loads the bank list, and starts the bank authorization after selection.

Flow Summary

  1. Your page renders a container for the bank selector.
  2. The SDK calls your server to create a payment and gets payLink.
  3. The bank selector is rendered in an iframe or inline mode.
  4. When the payer selects a bank, the SDK calls your server to start the payment.
  5. Your server returns the authUrl, and the SDK redirects the payer.

Client Example

<div id="bank-selector"></div>
<script src="https://sdk-sandbox.trustistecommerce.com/js/sdk.js?client-id=YOUR_CLIENT_ID" async></script>
<script>
window.trustistReadyCallback = function () {
    trustist.ecommerce.EmbeddedBankPayment({
        createPayment: () => {
            return fetch("/api/payments", {
                method: "post",
                headers: {
                    "Accept": "application/json",
                    "Content-Type": "application/json"
                },
                body: JSON.stringify({
                    amount: 99.99,
                    reference: "ORDER-12345",
                    returnUrl: window.location.origin + "/checkout/complete"
                })
            })
            .then((response) => response.json())
            .then((payment) => ({
                paymentId: payment.id,
                payIdString: payment.payIdString,
                payLink: payment.payLink,
                payerServicesUrl: payment.payerServicesUrl
            }));
        },
        startPayment: (request) => {
            return fetch("/api/payments/" + request.paymentId + "/start", {
                method: "post",
                headers: {
                    "Accept": "application/json",
                    "Content-Type": "application/json"
                },
                body: JSON.stringify({
                    bankId: request.bankId,
                    countryCode: request.countryCode,
                    payIdString: request.payIdString
                })
            })
            .then((response) => response.json());
        },
        bankSelector: {
            container: "#bank-selector",
            mode: "iframe",
            countryCode: "GB",
            paymentRails: ["FASTER_PAYMENTS", "SEPA_INSTANT"],
            showCountrySelector: true,
            minHeight: "560px"
        },
        qr: {
            enabled: true
        },
        onStatus: (message) => console.log(message),
        onPaymentStatus: (status) => console.log(status),
        onPaymentComplete: (status) => console.log("Payment complete", status),
        onError: (err) => console.error(err)
    }).render();
};
</script>

Bank Selector Options

Option Description
container CSS selector for the element where the selector will render.
mode iframe or inline rendering mode.
countryCode Two-letter country code to scope the bank list.
paymentRails Filter banks by supported rails, for example ["FASTER_PAYMENTS", "SEPA_INSTANT"].
showCountrySelector Show or hide the country selector when supported.
allowedBankIds Limit the bank list to specific bank IDs.
allowedOrigins Restrict accepted postMessage origins for iframe mode.
targetOrigin Origin to receive status messages from the iframe selector.
minHeight Minimum height for the iframe selector.

Defaults: for GBP payments, the selector assumes countryCode="GB", filters to FASTER_PAYMENTS, and hides the country selector unless you explicitly enable it.

If you are not using the SDK, you can append the same parameters directly to the payLink and use the /embedded/bank-selector endpoint yourself. 

https://pay.trustist.com/embedded/bank-selector?payIdString={payIdString}&countryCode=GB&paymentRails=FASTER_PAYMENTS&showCountrySelector=false&showQr=false

Server Responsibilities

  • Create a payment and return paymentId, payIdString, and payLink.
  • Start the payment when the payer selects a bank and return authUrl.
  • Verify final status when the payer completes the flow.

Retry is disabled by default for TE API payments. To allow retries, set workflow.allowRetryOnFailure when you create the payment on your server.

Next Steps