Lite SDK (Payment Web)

This page documents a legacy SDK. Starting a new integration? Use the Yuno SDK. Already on a legacy SDK? Follow the migration guide.The new Yuno SDK (Web v2.x, iOS v3.x, Android v3.x) replaces the Full, Lite, Seamless, Render, Headless, and Secure Fields SDKs with one API across every platform. Legacy SDKs remain supported side by side during the transition and are scheduled for deprecation in 2027. Contact your Account Manager for migration planning.

Orientation: Choosing Your Integration Flow, before you begin, please review the Official Integration Flow.

Standard Flow (Full Checkout): Recommended for most merchants. Yuno handles the UI, security, and automatic updates for payment methods.
Custom Flow (This SDK): Use this only if you require full control over the UX. Note: You will be responsible for manually handling payment statuses, 3DS transitions, and fraud routing data collection.

Follow this step-by-step guide to implement and enable Yuno’s Lite Web SDK payment capability in your app.

Step 1: Include the library in your project

New SDK equivalent for Steps 1 and 2: Install. The integration guide provides three flexible methods:

Direct HTML script inclusion
Dynamic JavaScript injection
NPM module installation

Choose the integration method that best suits your development workflow and technical requirements. After completing the SDK integration, you can proceed with the following steps to implement the Lite functionality.

TypeScript LibraryIf you are using TypeScript, Yuno offers a library that provides access to all available methods in the Yuno Web SDK.

Step 2: Initialize SDK with the public key

Initialize the Yuno SDK in your JavaScript application by providing a valid PUBLIC_API_KEY:

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

CredentialsSee the credentials page for more information: /reference/getting-started/authentication

Step 3: Create a checkout session

New SDK equivalent: Create the checkout session. To initialize the payment flow, create a new checkout_session using the Create checkout session endpoint.

First, create a customer or retrieve an existing customer ID
Include it when creating the checkout_session

Control Authorization and CaptureTo control authorization and capture with cards, send payment_method.detail.card.capture on the Create Payment request your backend sends from createPayment: set false to authorize only, true to capture immediately. Yuno reads this field from the payment request. See Cancel and capture flow.

Key parameters

Parameter	Required	Description
`amount`	Yes	The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount in that currency).
`alternative_amount`	No	An alternative currency representation of the transaction amount with the same structure as `amount` (`currency` and `value`). Useful for multi-currency scenarios. For example, you can display prices to customers in their preferred currency (for example, USD) while processing the payment in the local currency (for example, COP).

onPaymentMethodSelect EventFor all APMs, including Google Pay, Apple Pay, and PayPal, onPaymentMethodSelected is triggered as soon as the customer chooses the payment method (before the payment flow begins). Define onPaymentMethodSelected in await yuno.startCheckout() before await yuno.mountCheckoutLite().

Step 4: Start the checkout process

New SDK equivalent for Steps 4 to 6: Lite mode migration. Use the configuration below to provide a lite and user-friendly payment experience for your customers:

await yuno.startCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "US",
  language: "en-US",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  onLoading: (args) => console.log(args),
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
  card: {
    type: "extends",
    styles: "",
    cardSaveEnable: false,
    texts: {},
  },
  texts: {},
  async createPayment(oneTimeToken, tokenWithInformation) {
    // Read ACH bank name if needed: const bankName = tokenWithInformation.bank_transfer?.bank_name;
    await createPayment({ 
      oneTimeToken, 
      checkoutSession,
      vault_on_success: true 
    });
    await yuno.continuePayment({ showPaymentStatus: true });
  },
  onPaymentMethodSelected(data) {
    console.log("Payment method selected:", data);
  },
  async paymentResult(data) {
    console.log("Payment result:", data);
    await yuno.hideLoader();
  },
  async error(error, data) {
    console.error("An error occurred:", error);
    await yuno.hideLoader();
  },
});

When using startCheckout, specify the callbacks to handle payments. You can also customize the checkout interface using the texts objects.

Parameters

Configure the lite checkout with the following options:

Parameter	Description
`checkoutSession`	Refers to the current payment’s checkout session. Example: `438413b7-4921-41e4-b8f3-28a5a0141638`.
`elementSelector`	The HTML element where the checkout will be rendered.
`countryCode`	This parameter specifies the country for which the payment process is being set up. Use an `ENUM` value representing the desired country code. You can find the full list of supported countries and their corresponding codes on the Country Coverage page.
`language`	Language for payment forms. Use any code listed in Supported languages. Example: `en-US`. Defaults to browser language when available.
`showLoading`	Controls the visibility of the Yuno loading/spinner page during the payment process. Default: `true`.
`onLoading`	Required to receive notifications about server calls or loading events during the payment process.
`issuersFormEnable`	Enables the issuer’s form (for example, a list of banks). Default: `true`.
`showPaymentStatus`	Shows the Yuno Payment Status page, which is useful when continuing a payment. Default: `true`.
`showPayButton`	Controls the visibility of the pay button in the customer or card form. Default: `true`.
`renderMode`	Specify how and where the forms will be rendered. The options available are:
	▪️ `type: modal` (default)
	▪️ `type: element` - If you select `element`, you must inform the `elementSelector` to specify where the form should be rendered.
`card`	Defines the configuration for the card form. It contains settings like custom styles and the save card option.
`texts`	Allows you to set custom button texts for card and non-card payment forms.
`createPayment(oneTimeToken, tokenWithInformation)`	Callback function for creating a payment. Receives `oneTimeToken` and `tokenWithInformation` (matching the SDK checkout token schema, e.g. `tokenWithInformation.bank_transfer?.bank_name` for ACH). Send the one-time token to your backend to create the payment via the API; then call `await yuno.continuePayment()` to resume the flow. Also call `continuePayment` for card payments that come back `DECLINED` or `ERROR` to run payment retry; otherwise call `unmountSdk` to clean up. See Payment retry.
`onPaymentMethodSelected`	Callback invoked when a payment method is selected, along with the method’s type and name.
`paymentResult`	Callback called after the payment is completed. It receives the payment status (for example, `SUCCEEDED`, `DECLINED`, `PENDING`, `ERROR`) and an optional `subStatus` qualifying it. See Shopper-cancelled steps.
`error`	Callback invoked when there is an error in the payment process. Receives error type and optional additional data.
`onChange`	Reports whether the payment form is complete. Receives `{ form: { isValid } }`. Use with `showPayButton: false` to control your own pay button. Available since v1.10.11.

PromotionsWhen Promotions is enabled for your organization, Lite checkout asks for a promotion quote as the shopper types the card, and createPayment receives it in tokenWithInformation.quote. Wallets aren’t a supported target for this release: mountExternalButtons doesn’t ask for a quote. See Promotions.

Customer and Merchant-Initiated TransactionsPayments can be initiated by the customer (CIT) or by the merchant (MIT). You find more information about their characteristics in Stored credentials.

Step 5: Mount the SDK

To present the checkout process based on the selected payment method, use the await yuno.mountCheckoutLite() function. This step ensures the SDK is properly mounted on your chosen HTML element.

await yuno.mountCheckoutLite({
  paymentMethodType: PAYMENT_METHOD_TYPE,
  vaultedToken: VAULTED_TOKEN,
});

See the Payment type page to view the complete list of payment method types you can use when mounting the SDK. The vaultedToken is optional. It represents a previously enrolled payment method. If you provide the vaultedToken, the user will not be required to provide the payment information again since it was provided in a previous transaction. After mounting, you must start the checkout flow by calling yuno.startPayment(). If you skip this call, the payment form will not open. Note that yuno.startPayment() also returns a promise and should be awaited.

Step 6: Start the payment flow (Required)

Call await yuno.startPayment() immediately after await yuno.mountCheckoutLite() to open the selected payment method UI:

await yuno.mountCheckoutLite({
  paymentMethodType: PAYMENT_METHOD_TYPE,
  vaultedToken: VAULTED_TOKEN,
});

await yuno.startPayment();

Alternatively, you can trigger the start from a user action such as a button click:

const payButton = document.querySelector('#button-pay');
payButton.addEventListener('click', async () => {
  await yuno.startPayment();
});

Demo AppIn addition to the code examples provided, you can access the Demo App for a complete implementation of Yuno SDKs (clone from the repository).

Check that a payment method will render before listing it

If you draw your own payment-method list, ask the SDK which methods will actually render for this shopper and checkout session before you show them. Call isPaymentMethodAvailable after startCheckout and hide every method that resolves to false. Otherwise the shopper can pick a method that is not enabled for the session, or a wallet the device cannot use, and see an empty box where the form or button should be.

await yuno.startCheckout({ checkoutSession, elementSelector: '#root', countryCode: 'US' });

const methods = ['CARD', 'GOOGLE_PAY', 'APPLE_PAY', 'PAYPAL'];
const answers = await Promise.all(
  methods.map((paymentMethodType) => yuno.isPaymentMethodAvailable({ paymentMethodType }))
);
const availableMethods = methods.filter((_, index) => answers[index]);

renderMyPaymentList(availableMethods);

The answer is the same decision the SDK takes when it renders that method, and the method never rejects. See isPaymentMethodAvailable for what is checked for each method.

Mount external buttons

You can use the mountExternalButtons method to render Google Pay and Apple Pay buttons in custom locations within your UI. This gives you control over where these buttons are displayed. Call it after startCheckout.

await yuno.startCheckout({ checkoutSession, elementSelector: '#root', countryCode: 'US' });

await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

A wallet button renders only when the payment method is enabled for the checkout session and passes the SDK’s device and browser check, for example Google Pay’s isReadyToPay() for the session’s configuration. The same code can therefore show a wallet button on one device or browser and not on another. On Web SDK 1.11.43 and later, or 1.10.35 and later, call isPaymentMethodAvailable for each wallet before mounting it, and only show the containers of the wallets that resolve to true.

External button parameters

Parameter	Description
`paymentMethodType`	The payment method type. Must be either `'APPLE_PAY'` or `'GOOGLE_PAY'`.
`elementSelector`	The CSS selector for the HTML element where the button should be rendered (for example, `'#apple-pay'`, `'.button'`).

Unmounting buttons

You can unmount a single external button by payment method type:

await yuno.unmountExternalButton('APPLE_PAY');

Or unmount all external buttons at once:

await yuno.unmountAllExternalButtons();

Unmounting the SDK

For explicit cleanup of the Yuno SDK, for example when a user cancels the flow or you need to remove the SDK from the DOM, use the unmountSdk() method:

await yuno.unmountSdk();

PayPal REDIRECT Workflow

The Yuno SDK supports a REDIRECT workflow for PayPal. This workflow is useful when PayPal was not initialized at the start of the SDK or when using a pre-existing PayPal orderId.

PaypalButtonModal: If PayPal is not initialized, the SDK can render the PayPal button inside a modal.
Workflow: The REDIRECT workflow skips fraud detection and OTT creation, utilizing the provided orderId.

// Example PayPal configuration
await yuno.startCheckout({
  // ... other config
  paypal: {
    workflow: 'REDIRECT',
    orderId: 'PAYPAL_ORDER_ID',
  }
});

Enrolling payment methods in lite flow

New SDK equivalent: Enrollment. You can enroll payment methods (store cards for future use) directly during the lite payment flow by setting payment_method.vault_on_success = true on the Create Payment request your backend sends from createPayment — nested under payment_method, as shown below. In the Lite flow your server creates the payment, so this is where the flag belongs; setting it on the checkout session is the Seamless pattern, where the SDK creates the payment. When vault_on_success is set to true:

The payment method will be automatically enrolled if the payment status is SUCCEEDED
If the payment does not succeed, no vaulting will occur
The payment response will include a vaulted_token that you can use for future transactions

Example (partial excerpt — only the relevant fields are shown):

{
    "account_id": "...",
    ...
    "payment_method": {
        "vault_on_success": true
    }
}

Vaulting RequirementsTo generate and receive a vaulted_token when vault_on_success = true, the payment must reference an existing Yuno customer through customer_payer.id in the checkout session. Creating or sending the customer data inline inside the payment request does not create the customer in Yuno’s system, so no vaulting will occur.

For more information about enrolling payment methods, see Enroll Payment Methods.

Error handling

New SDK equivalent: the onStatus controller. Handle errors returned by the SDK in your app, such as failed payments or validation errors. For HTTP status and response codes, see Status and response codes in the API reference.

Stay updated

Visit the changelog for the latest SDK updates and version history.

Overview

Seamless SDK

Lite SDK

Headless SDK

Card Enrollment

Additional Features

Resources

Additional Platforms

Web Frameworks

Validate your integration

External Native Modules

Step 1: Include the library in your project

Step 2: Initialize SDK with the public key

Step 3: Create a checkout session

Key parameters

Step 4: Start the checkout process

Parameters

Step 5: Mount the SDK

Step 6: Start the payment flow (Required)

Check that a payment method will render before listing it

Mount external buttons

External button parameters

Unmounting buttons

Unmounting the SDK

PayPal REDIRECT Workflow

Enrolling payment methods in lite flow

Error handling

Stay updated

​Step 1: Include the library in your project

​Step 2: Initialize SDK with the public key

​Step 3: Create a checkout session

​Key parameters

​Step 4: Start the checkout process

​Parameters

​Step 5: Mount the SDK

​Step 6: Start the payment flow (Required)

​Check that a payment method will render before listing it

​Mount external buttons

​External button parameters

​Unmounting buttons

​Unmounting the SDK

​PayPal REDIRECT Workflow

​Enrolling payment methods in lite flow

​Error handling

​Stay updated

Step 1: Include the library in your project

Step 2: Initialize SDK with the public key

Step 3: Create a checkout session

Key parameters

Step 4: Start the checkout process

Parameters

Step 5: Mount the SDK

Step 6: Start the payment flow (Required)

Check that a payment method will render before listing it

Mount external buttons

External button parameters

Unmounting buttons

Unmounting the SDK

PayPal REDIRECT Workflow

Enrolling payment methods in lite flow

Error handling

Stay updated