TrustistEcommerce JS SDK Reference – Server‑to‑Server Payments

This page documents the `trustist.ecommerce.ServerToServerPayment` API exactly as implemented, including options, callbacks, and behaviors.

Script include #

<script src="https://sdk-sandbox.trustistecommerce.com/js/sdk.js?client-id={{client_id}}" async></script>

Factory #

const payment = trustist.ecommerce.ServerToServerPayment(options)

Options (object) #

– `createPayment(browserData: object) => Promise<Payment>` (required)
  – Called by the SDK. You must call your backend, passing `browserData` through to it, and return the TrustistEcommerce API response JSON to the SDK.
  – Expected resolve values:
    – `{ id, status: “COMPLETE”, requiredAction: null }`
    – `{ id, status: “PENDING_ACTION”, requiredAction: { type: “redirect”, url } }`
  – On failure, reject with `Error(message)`; the SDK will surface this via `paymentFailed`.

– `paymentComplete(payment: Payment)` (optional)
  – Called when the payment is completed (frictionless or after bank authentication).
  – `payment` includes `id` and `status`.

– `paymentFailed(error: any)` (optional)
  – Called when creation or authentication fails. `error.reason` or `error.message` may be present.

– `challengeDisplayMode` (string, optional)
  – Controls how authentication is presented. Values:
    – `’lightbox’` (default): Overlay modal with an iframe
    – `’iframe’`: Inline iframe appended to the page
    – `’redirect’`: Full page redirect; returns to the original page after completion

– `redirectReturnUrl` (string, optional)
  – Only used for `redirect` mode. If absent, current page URL is used.

Payment type (returned to callbacks) #

interface Payment {
  id: string;
  status: 'COMPLETE' | 'PENDING_ACTION' | string;
  requiredAction?: { type: 'redirect'; url: string } | null;
}

Methods #

`render(pathOrArgs)` #

– Renders the Trustist button to initiate payment.
– Parameters:
  – `pathOrArgs: string | { path: string; buttonText?: string; buttonColour?: string; textColour?: string; buttonHoverColour?: string; textHoverColour?: string; loadingText?: string; }`
– Behavior:
  – Injects a stylesheet and renders a button into `path`.
  – On click, collects browser data, calls `createPayment(browserData)`, and then:
    – If `requiredAction` exists: opens the hosted authentication page (respecting `challengeDisplayMode`) and completes automatically.
    – If `status` is `COMPLETE`: immediately triggers `paymentComplete`.

`collectBrowserData()` #

– Returns the browser data object used by the SDK:

{
  "browserJavaEnabled": boolean,
  "browserJavascriptEnabled": true,
  "browserLanguage": string,
  "browserColorDepth": number,
  "browserScreenHeight": number,
  "browserScreenWidth": number,
  "browserTZ": string,
  "browserUserAgent": string,
  "browserAcceptHeader": "*/*",
  "browserIP": string, // placeholder; set true IP server-side
  "browserJavaEnabledString": "true" | "false",
  "challengeWindowSize": "05", // full window default
  "deviceChannel": "02" // Browser
}

`handle3DSChallenge(challengeUrl, completeCallback)` #

– Opens the hosted authentication page using the current `challengeDisplayMode` and invokes `completeCallback(result)` when finished.
– Modes:
  – `’redirect’`: Navigates to the page and returns using appended `merchantOrigin` and optional `returnUrl`.
  – `’lightbox’`: Overlays a modal containing an iframe; listens for postMessage completion events.
  – `’iframe’`: Inserts an inline iframe; listens for postMessage completion events.

Redirect return handling #

– On redirect completion, the SDK detects `trustist_3ds_*` query params, cleans them from the URL, and triggers `paymentComplete` or `paymentFailed` accordingly.

Styling #

– The button injected by `render` supports:
  – `buttonText`, `buttonColour`, `textColour`, `buttonHoverColour`, `textHoverColour`, `loadingText`

Example #

<div id="trustistServerToServerPayment"></div>

<script>
  window.trustistReadyCallback = function () {
    trustist.ecommerce.ServerToServerPayment({
      challengeDisplayMode: 'lightbox',
      createPayment: async (browserData) => {
        const payload = { /* amount, reference, payerEmail, cardDetails, browserData */ };
        const r = await fetch('/api/payments/server-to-server', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) });

        if (!r.ok) { const e = await r.json().catch(()=>({error:'Payment failed'})); throw new Error(e.error); }

        return await r.json();
      },

      paymentComplete: (payment) => {
        if (payment.status === 'COMPLETE') window.location.href = '/thank-you?payment=' + payment.id;
      },

      paymentFailed: (e) => console.error(e)
    }).render({ path: '#trustistServerToServerPayment', buttonText: 'Pay Now' });
  };
</script>

Notes and Guarantees #

– `requiredAction.type` is always `’redirect’` when authentication is needed.
– The hosted page finalises the payment; `paymentComplete` receives the final status.
– For fulfilment, rely on webhooks rather than client callbacks.