Checkout Widget: Drop-In PCI-Safe Payment Form Setup

The Checkout Widget is a fully rendered, PCI-safe payment form you drop into your page. It handles card inputs, saved-card display, and the “Save this card” consent checkbox — without you building any form HTML. If you want full control over layout and styling, use Hosted Fields instead.

Basic setup

Call sdk.checkout() after initializing the SDK. The widget mounts itself into the DOM automatically.

const checkout = sdk.checkout({
  shopperId: sdk.sessionData().customerId,
  vaultConsentEnabled: true,
  onSavedMethodSelected: (token) => {
    // A returning shopper picked a saved card
    // Charge it directly using sdk.authorizeToken(token)
  },
})

To mount the widget into a specific element, pass a CSS selector:

const checkout = sdk.checkout({
  container: '#checkout-container',
  vaultConsentEnabled: true,
})

Language (`locale`)

Set locale to choose the language of the widget’s built-in text: 'en', 'es', or 'pt'. If you omit it, the widget uses the shopper’s browser language and falls back to English when that language isn’t supported.

const checkout = sdk.checkout({
  locale: 'es',
})

locale covers all of the widget’s own text, not only the consent checkbox: the pay and subscribe buttons, the “Secured by Therius” footer, card-form labels and placeholders, saved-card text, the subscription and card-on-file disclosures, Pix and Affirm panel text, and the common decline and error messages. Your own page content and any text returned by a payment provider are not translated.

Callbacks

Callback	Fires when
`onActionComplete(result)`	A payment reaches a final state after a popup action (3DS or redirect) or after the widget’s built-in authorize call. `result` contains `status`, `paymentCode`, and, on the resume path, the full `payment`. Use it to show the final result in your UI.
`onDeclined(info)`	A payment is declined and the widget has recovery guidance. `info` contains `reason` and `recoveryAction` (`'retry'`, `'switch_method'`, or `'terminal'`). The widget already shows its own recovery UI, so use this only to log or report the decline.
`onError(error)`	The widget hits an error that isn’t a decline.
`onMethodChange(method)`	The shopper switches payment method tab.

onNonce, onApm, and onWalletToken are optional interceptors. Leave them out and the widget calls the matching SDK method itself and reports the outcome through onActionComplete or onError. Supply them only if you need to route the payment through your own server.

When you authorize from your own server, pass the shopper’s real IP address as ipAddress on the payment request. Your server’s address is not the shopper’s, and fraud scoring and some providers rely on the real one. The widget looks the address up for you and hands it to onNonce, onApm, and onSavedMethodSelected as shopper.ipAddress (it is absent if the lookup fails):

onNonce: async (nonce, ddcSessionId, vaultConsent, shopper) => {
  await fetch('/pay', {
    method: 'POST',
    body: JSON.stringify({ nonce, ddcSessionId, ipAddress: shopper?.ipAddress }),
  })
}

When the widget authorizes by itself, Therius uses the address of the shopper’s connection, so no extra step is needed.

Saved-card picker

If the session was created with a customerId and that shopper has previously vaulted cards, the widget automatically renders a card picker above the new-card form. Cards are displayed as brand / last 4 / expiry — no PAN is ever returned to the browser. When the shopper selects a saved card, onSavedMethodSelected fires with the card’s token. Charge it immediately without a nonce:

const checkout = sdk.checkout({
  onSavedMethodSelected: async (token) => {
    const result = await sdk.authorizeToken(token, {
      amount: { currency: 'USD', value: 4999, exponent: 2 },
    })
    if (result.actionRequired) {
      const finalResult = await sdk.handleAction(result.actionRequired)
    }
  },
})

The saved-card list is backed by GET /sdk/vaulted-methods and is scoped to the session’s own shopper — the browser cannot enumerate a different shopper’s cards.

Combine vaultConsentEnabled: true with a customerId in your POST /sdk/session call for the best returning-shopper experience. When a shopperId is present in the session, the “Save this card” checkbox appears automatically.

For a new card entered through the widget, retrieve the nonce after the shopper submits the form and use it the same way as with hosted fields:

checkout.on('submit', async ({ nonce }) => {
  const result = await sdk.authorize(nonce)
  if (result.actionRequired) {
    const finalResult = await sdk.handleAction(result.actionRequired)
  }
})

Alternatively, call sdk.authorize(nonce) directly after widget submission to let the SDK manage the full authorize-and-action loop in one call.

Handling 3DS

3DS is handled identically to hosted fields. If the charge result includes actionRequired, pass it to sdk.handleAction:

if (result.actionRequired) {
  const finalResult = await sdk.handleAction(result.actionRequired)
}

sdk.handleAction opens the 3DS challenge iframe, waits for completion, and resolves with the final PaymentResult. You do not need to write separate logic for different challenge types.

vaultConsentEnabled only shows the “Save this card” checkbox when a shopperId is present in the session. If no customerId was passed to POST /sdk/session, the checkbox is hidden regardless of this setting.

If you passed cardOnFile when creating the session (see Merchant-managed subscriptions), the widget shows a fixed “card will be saved” disclosure instead of the vaultConsentEnabled checkbox — the card is saved unconditionally, so there’s nothing to opt into.

Overview

Card Collection

Wallets & More

Checkout Widget: Drop-In PCI-Safe Payment Form Setup

Basic setup

Language (`locale`)

Callbacks

Saved-card picker

Charging a new card from the widget

Handling 3DS

​Basic setup

​Language (locale)

​Callbacks

​Saved-card picker

​Charging a new card from the widget

​Handling 3DS

Basic setup

Language (`locale`)

Callbacks

Saved-card picker

Charging a new card from the widget

Handling 3DS