Embedded Bank Payments

Embedded payments keep the bank selector inside your checkout while Trustist handles the Pay by Bank 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 () {
    const currency = "GBP";

    trustist.ecommerce.EmbeddedBankPayment({
        createPayment: () => {
            return fetch("/api/payments", {
                method: "post",
                headers: {
                    "Accept": "application/json",
                    "Content-Type": "application/json"
                },
                body: JSON.stringify({
                    amount: 99.99,
                    currency: currency,
                    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",
            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.
currency Optional compatibility input. In iframe mode, the selector can infer bank filtering from the payment behind payIdString.
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.
Recommended pattern: create the payment with the correct currency and let the iframe selector infer the appropriate bank filtering from that payment.

Defaults: in iframe mode, the selector can infer bank filtering from the payment currency and continue to use countryCode and showCountrySelector for bank-list presentation.

If you are not using the SDK, existing integrations can append the same parameters directly to the payLink and use the /embedded/bank-selector endpoint yourself. For payment flows, you normally do not need to append currency or paymentRails; for AIS-only flows, countryCode is normally enough. 

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

Inline mode and specialist bank-directory integrations can continue to use advanced filters directly when needed.

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