Web Payments

The Web SDK makes it easy to integrate payment flows into your web and browser-based experiences.

Additional resources

Yuno offers a TypeScript library that complements the SDK.
See Choose the right integration for you if you’re unsure which flow to follow.
See the Demo App for a complete implementation (clone from the repository).

Requirements

A customer created in Yuno and a checkout session: reference each API when setting up your backend.
Public API key (obtain from the Yuno Dashboard → Developers > Credentials)

The first step is including the library in your project. The integration guide provides three flexible methods:

Direct HTML script inclusion: Add the script tag to your page.
Dynamic JavaScript injection: Load the SDK at runtime.
NPM module installation: Install via npm (recommended).

Option 1: NPM (Recommended)

npm install @yuno-payments/sdk-web

When using the NPM package, you can use the loadScript method to handle script loading with Subresource Integrity (SRI) support:

import { loadScript } from '@yuno-payments/sdk-web';

const yuno = await loadScript({
  apiKey: 'YOUR_PUBLIC_KEY',
  integrity: 'sha384-...', // Find the hash in our GitHub repository
});

Option 2: HTML Script Tag

<script 
  src="https://sdk-web.y.uno/v1.10/main.js"
  async
  defer
></script>

v1.10 is a global path: it receives every patch released on that line, so you get fixes without changing your integration.Do not add an integrity attribute to this URL. Because the file is republished on each patch release, any hash you pin to it stops matching and the browser blocks the script. Subresource Integrity requires the immutable full-version URL instead — see Subresource Integrity.

Option 3: Dynamic JavaScript

const script = document.createElement('script');
script.src = 'https://sdk-web.y.uno/v1.10/main.js';
script.async = true;
script.defer = true;
document.head.appendChild(script);

Once Step 1 is complete, continue with the full-checkout integration.

Parameters

These are the parameters covered in this guide. For the full list of parameters and callbacks, see the Web SDK Common Reference.

Parameter	Description
`checkoutSession`	Checkout session ID from your backend (Create checkout session API). Required for all flows.
`elementSelector`	CSS selector for the element where the SDK mounts (e.g. `#root`).
`countryCode`	ISO country code where the payment runs (e.g. `FR`, `US`).
`language`	Language code for the UI (e.g. `fr-FR`, `ar`). Optional; defaults to browser language when available.
`showLoading`	Show SDK loading spinner. Optional.
`showPaymentStatus`	Show payment result screen. Optional.
`yunoCreatePayment(oneTimeToken)`	Callback: send one-time token to your backend to create the payment; then call `await yuno.continuePayment()`.
`yunoPaymentResult(status, subStatus)`	Callback: payment finished. Receives payment status (e.g. `SUCCEEDED`, `DECLINED`, `PENDING`) and an optional `subStatus` qualifying it. See Shopper-cancelled steps.
`yunoError(message, data)`	Callback: error during the flow.
`onLoading`	Callback: loading state updates.
`card`	Card form options (e.g. `onChange`, `isCreditCardProcessingOnly`). Optional.

full-checkout

Implement Yuno’s Full integration: pre-built checkout UI with full control over branding, forms, and flow. Use this when you want Yuno to render the checkout experience while you manage customer and checkout session creation on your backend.

Step 1: Include the library in your project

Follow the steps in Include the library in your project above.

Step 2: Initialize the SDK

After including the library (step 1), initialize the SDK. See Quickstart guide for initialization.

Step 3: Start the checkout process

Use the await yuno.startCheckout() function to start the checkout process with the necessary parameters. See Parameters for all options. For styling, themes, and additional configurations, see SDK customizations.

await yuno.startCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "FR",
  language: "fr-FR",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  card: {
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
  onLoading: (args) => {
    console.log(args);
  },
  onPaymentMethodSelected: () => {
    console.log("Payment method selected");
  },
  yunoPaymentResult: (status) => {
    console.log("Payment result:", status);
  },
  yunoError: (message, data) => {
    console.error("Payment error:", message, data);
  },
  async yunoCreatePayment(oneTimeToken) {
    await createPayment({ oneTimeToken, checkoutSession });
    await yuno.continuePayment({ showPaymentStatus: true });
  },
});

By default, Yuno SDK renders as a modal. You can specify the element where the SDK will render. See Render mode for details. For all APMs (Google Pay, Apple Pay, PayPal), onPaymentMethodSelected triggers when the customer chooses the payment method (before the payment flow begins). Define onPaymentMethodSelected in await yuno.startCheckout() before await yuno.mountCheckout(). For PayPal, the payment sheet opens immediately after selection—no extra confirmation click required.

Step 4: Mount the SDK

Display the payment methods:

await yuno.mountCheckout();

Step 5: Initiate the payment process

Call await yuno.startPayment() to initiate the payment flow after the user selects a payment method:

const PayButton = document.querySelector("#button-pay");

PayButton.addEventListener("click", async () => {
  await yuno.startPayment();
});

Step 6: Get the OTT (one-time token)

After the customer fills out the requested data in Yuno’s payment forms, the SDK provides the one-time token. The configuration function yunoCreatePayment(oneTimeToken) is then triggered with the one-time token.

yunoCreatePayment(oneTimeToken);

You can also use tokenWithInformation to receive additional information provided by the customer in the checkout, such as installments or document type/number:

yunoCreatePayment(oneTimeToken, tokenWithInformation);

Use Yuno’s default loader or implement your own with the required configuration.

Step 7: Create the payment

Create a payment using the Create Payment endpoint. The merchant’s backend should call this endpoint to create the payment in Yuno using the one-time token and checkout session. After Step 6, the basic payment flow is implemented. Test using the checkout session and one-time token. For additional features, see Complementary features. Required: After creating a payment, integrate the continuePayment method. When the API response sets sdk_action_required to true, call await yuno.continuePayment() to present the necessary screens. Card payments that come back DECLINED or ERROR also require calling continuePayment to run payment retry (keeps the card form open with the decline shown); if neither of those applies, call unmountSdk to clean up. See Payment retry for details.

`continuePayment` return value or null

For payment methods that require merchant-side action (e.g., when the payment provider requires a redirect URL in a webview), the await yuno.continuePayment() method returns either an object with the following structure or null:

{
  action: 'REDIRECT_URL'
  type: string
  redirect: {
    init_url: string
    success_url: string
    error_url: string
  }
} | null

When the method returns an object, you can handle your application’s payment flows that require custom redirect handling. When it returns null, no additional merchant-side action is needed.

Complementary features

For styling, themes, form options, and additional configurations, see SDK customizations. Changelog.

Common reference

For full parameter and customization details, see the Web SDK Common Reference.

Overview

Seamless SDK

Lite SDK

Headless SDK

Card Enrollment

Additional Features

Resources

Additional Platforms

External Native Modules

Additional resources

Requirements

Parameters

full-checkout

Step 1: Include the library in your project

Step 2: Initialize the SDK

Step 3: Start the checkout process

Step 4: Mount the SDK

Step 5: Initiate the payment process

Step 6: Get the OTT (one-time token)

Step 7: Create the payment

`continuePayment` return value or null

Complementary features

Common reference

​Additional resources

​Requirements

​Parameters

​full-checkout

​Step 1: Include the library in your project

​Step 2: Initialize the SDK

​Step 3: Start the checkout process

​Step 4: Mount the SDK

​Step 5: Initiate the payment process

​Step 6: Get the OTT (one-time token)

​Step 7: Create the payment

​continuePayment return value or null

​Complementary features

​Common reference

Additional resources

Requirements

Parameters

full-checkout

Step 1: Include the library in your project

Step 2: Initialize the SDK

Step 3: Start the checkout process

Step 4: Mount the SDK

Step 5: Initiate the payment process

Step 6: Get the OTT (one-time token)

Step 7: Create the payment

`continuePayment` return value or null

Complementary features

Common reference