Hosted Redirect Payments

Use the JavaScript SDK to render a payment button and redirect the payer to a Trustist-hosted checkout. Your server creates the payment, the SDK handles the redirect, and your page receives the return callback.

SDK optional: hosted redirect payments can also be implemented without the JavaScript SDK by creating a payment in your backend and redirecting the payer to the returned payLink.

Flow Summary

  1. Render a payment button with the SDK.
  2. When clicked, the SDK calls your server to create a payment.
  3. Your server returns the payLink.
  4. The SDK redirects the payer to the hosted payment page.
  5. After completion, the payer returns to your page with tr-payment-id.

Client Example

<div id="payment-button"></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.Payment({
        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) => payment.payLink);
        },
        paymentComplete: (payment) => {
            return fetch("/api/payments/" + payment["tr-payment-id"], {
                method: "get"
            })
            .then((response) => response.json())
            .then((paymentStatus) => {
                if (paymentStatus.status === "COMPLETE") {
                    window.location.href = "/thank-you";
                }
            });
        },
        bankSelector: {
            countryCode: "GB",
            showCountrySelector: false
        },
        qr: {
            enabled: true
        }
    }).render({
        path: "#payment-button",
        buttonText: "Pay now",
        loadingText: "Redirecting..."
    });
};
</script>

Server Responsibilities

  • Create a payment using the Trustist Ecommerce API.
  • Return the payLink to the SDK.
  • On return, verify payment status using tr-payment-id.

To allow customers to retry a failed payment, set workflow.allowRetryOnFailure when you create the payment. The default behaviour is to return the customer to your site on failure.

Filtering the Bank List

Hosted payments can apply bank filters via the bankSelector option. The SDK appends the selected filters to the pay link before redirecting.

Recommended pattern: create the payment with the correct currency and let the hosted payment page infer the appropriate bank filtering from that payment.

Defaults: the hosted page infers bank filtering from the payment currency and continues to use countryCode and showCountrySelector only for bank-list presentation.

If you are not using the SDK, existing integrations can continue to append bank-filter query parameters directly to the payLink. 

https://pay.trustist.com/pay/{payIdString}?countryCode=GB&showCountrySelector=false&showQr=false
Option Example Description
countryCode "GB" Limit the bank list to a specific country.
currency "GBP" Optional compatibility input. Hosted payment pages already infer bank filtering from the payment currency.
showCountrySelector false Hide the country selector dropdown on the hosted payment page.

Existing integrations can continue to use advanced bank-directory filters directly when needed, but most payment flows do not need to.

QR Options

Hosted checkout shows a Trustist QR code on desktop by default. You can suppress it if you want to force on-screen bank selection.

Option Example Description
qr.enabled false Disable the desktop QR code on the hosted payment page.

Next Steps