Web SDK

Use the DEUNA Web SDK to render Payment Widget, Payment Vault, Click to Pay, native wallets, vouchers, and next actions in a modal or inside a page. The browser SDK is distributed as a classic script through the DEUNA CDN.

Load the SDK#

Pin the SDK version used by your integration. Test a newer release in sandbox before changing this URL in production.

<script
  crossorigin
  src="https://cdn.deuna.io/web-sdk/v1.7/index.js">
</script>

The script exposes the singleton window.DeunaSDK. It also supports DeunaSDK.newInstance() when a page needs isolated SDK instances.

Initialize#

Initialize once with the public API key for the selected environment. Set the environment explicitly; the SDK defaults to production when env is omitted.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
});

Open Payment Widget#

Create the order on your backend, return its token to the browser, and open Payment Widget:

await DeunaSDK.initPaymentWidget({
  orderToken,
  language: 'en',
  callbacks: {
    onSuccess: async (order) => {
      await DeunaSDK.close();
      showConfirmation(order);
    },
    onError: (error) => showRetry(error),
    onClosed: (action, metadata) => {
      console.log('Widget closed', action, metadata);
    },
    onEventDispatch: (event, payload) => {
      analytics.track(event, payload);
    },
  },
});

Use the callback to update the interface. Confirm and fulfill the final order from a verified webhook rather than trusting browser state alone.

Choose a presentation mode#

Modal is the default. The SDK owns the overlay and close() dismisses it.

For an embedded widget, use both mode: 'target' and a CSS selector. Update the container height from onResize so content is not clipped.

<div id="payment-widget"></div>

await DeunaSDK.initPaymentWidget({
  orderToken,
  mode: 'target',
  target: '#payment-widget',
  callbacks: {
    onResize: ({height}) => {
      document.querySelector('#payment-widget').style.height = `${height}px`;
    },
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
  },
});

Control submission from your page#

Hide the widget’s pay button when your page owns the final call to action. Validate before submitting and disable your button while the promise is pending.

await DeunaSDK.initPaymentWidget({
  orderToken,
  hidePayButton: true,
  callbacks,
});

payButton.addEventListener('click', async () => {
  if (!(await DeunaSDK.isValid())) return;

  payButton.disabled = true;
  const result = await DeunaSDK.submit();
  payButton.disabled = false;

  if (result.status === 'error') showRetry(result);
});

The active widget also exposes getWidgetState(), refetchOrder(), and setCustomStyles(...). Call setCustomStyles only from the card-BIN or installment callbacks documented for the payment flow.

Available experiences#

Payment Vault and Click to Pay

initElements opens Payment Vault by default. Supply types to select a different Elements experience.

await DeunaSDK.initElements({
  orderToken,
  userInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    email: 'ada@example.com',
  },
  types: [{name: 'vault'}],
  callbacks: {
    onSuccess: (credential) => useSavedCredential(credential),
    onError: (error) => showRetry(error),
    onClosed: (action) => console.log(action),
  },
});

Use {name: 'click_to_pay'} for Click to Pay. When you already have an authenticated DEUNA user, pass userToken instead of userInfo.

Apple Pay and Google Pay

When you render a merchant-owned wallet button, check availability before showing it. Run this step before the click so Apple Pay can open directly from the user gesture.

const userInfo = {email: 'ada@example.com'};
const availableWallets = await DeunaSDK.getWalletsAvailable({
  orderToken,
  userInfo,
});

applePayButton.hidden = !availableWallets.includes('APPLE_PAY');

applePayButton.addEventListener('click', () => {
  DeunaSDK.initElements({
    orderToken,
    userInfo,
    types: [{name: 'APPLE_PAY'}],
    callbacks: {
      onSuccess: (credential) => useSavedCredential(credential),
      onError: (error) => showRetry(error),
      onClosed: () => showPaymentMethods(),
    },
  });
});

Use GOOGLE_PAY for the equivalent Google Pay flow. See the Apple Pay guide and Google Pay guide for merchant and browser prerequisites.

Continue a pending action

Open Next Action only when the order response indicates that customer action is still required, such as a supported 3DS challenge or redirect.

await DeunaSDK.initNextAction({
  orderToken,
  callbacks: {
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Do not create a second order for this step. Reuse the token for the order that requires the next action.

Open a voucher

Use the voucher experience for supported cash or voucher-based payment methods.

await DeunaSDK.initVoucherWidget({
  orderToken,
  callbacks: {
    onSuccess: (order) => showVoucherInstructions(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Preload a widget#

Payment Widget and Elements can be created off-screen during initialization and shown later. Preloading reduces perceived opening time but uses network and browser resources earlier.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
  preloadWidgets: [
    {
      widget: 'payment',
      params: {language: 'en'},
    },
  ],
});

// After the backend returns the order token:
await DeunaSDK.initPaymentWidget({orderToken});

Preload only the experience the customer is likely to open. The later initPaymentWidget or initElements call supplies the order or user token and reveals the prepared widget.

Fraud-device data#

Payment Widget starts DEUNA device-data collection when it opens. If your flow needs the identifier before a widget opens, call generateFraudId(...) and send the returned value only through the documented order or risk flow.

const fraudId = await DeunaSDK.generateFraudId();

Provider-specific input and version behavior are documented in Integrate device fingerprint.

Callback and lifecycle reference#

Related guides and code#