First steps - Web

This page provides a comprehensive guide to initializing the DEUNA Web SDK in your application.

📘

Stable version: 1.6

Requirements

To use the DEUNA Web SDK, you must have:

• Knowledge of web development with JavaScript.
• An active account at DEUNA.
• Valid DEUNA credentials.

📘

If you experience any delays in obtaining your credentails, please contact [email protected].

Install the Web SDK

Web SDK initialization begins.

🚧

Follow security and privacy practices when handling user financial information.

1. Add the DEUNA Web SDK to your project

Load our SDK via the official URL for the desired environment.

📘

The DEUNA Web SDK can only be installed via CDN.

The attributecrossorigin provides support for CORS defining how the script element handles cross-origin calls.

Add the following script to your HTML file:

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

You can also add the DEUNA SDK dynamically using JavaScript.

Example

if (typeof DeunaSDK === "undefined") { // if the DEUNA's SDK is not added yet.
    var script = document.createElement("script");
    script.src = "https://cdn.deuna.io/web-sdk/v1.6/index.js";
    script.onload = function() {
       // Initialize the DEUNA's SDK and
       // display a widget
    };
    document.head.appendChild(script);
} else {
    //  display a widget
}

2. Choose your integration approach

DEUNA offers two integration approaches. We recommend Option 1 (Preloaded) for all new integrations, as it delivers the fastest experience for your shoppers.

Use the alternative approach only when you cannot preload the widget — for example, if the order token is not available until the shopper clicks Pay.

✅ Option 1 — Preloaded (Recommended)

The widget loads silently in the background during initialize. When your shopper is ready to pay, the widget appears with minimal delay.

How it works:

Widget Preloading separates widget initialization into two phases: heavy setup happens early (during initialize), while the user-facing display happens later (during initElements / initPaymentWidget). The iframe is created and configured in the background — hidden off-screen — so when the merchant is ready to show it, the widget appears perceived-instantly.

Initialize and choose your widget

Select the widget you want to preload and add it to the preloadWidgets array inside initialize. This is where you define your widget configuration, callbacks, and display options. Note: See the widget's specific section below for all available params.

 await DeunaSDK.initialize({
   publicApiKey: 'YOUR_PUBLIC_API_KEY', // Public key provided by DEUNA.
   env: 'production',
   preloadWidgets: [
     {
       widget: 'elements',  // or 'payment'
       params: {
         // See your widget's specific section below for all available params.
       }
     }
   ]
 });

Option 2 — Alternative (Fallback)

Use this approach only when you cannot preload the widget — for example, if the order token is not available until the shopper clicks Pay, and you have no opportunity to call initialize earlier in the page lifecycle.

In this flow, everything loads at once when the shopper initiates payment, which may result in a visible loading state.

await DeunaSDK.initialize({
  publicApiKey: "YOUR_PUBLIC_API_KEY", // Public key provided by DEUNA.
  env: "sandbox", // Test environment (sandbox) o production ready environment (production).
});

3. Choose the widget component

Continue the integration process following the specific instructions for each component.

Choose the component: