Lite SDK (Enrollment 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, React Native v2.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 enrollment capability in your app.

Step 1: Include the library in your project

Before proceeding with the Lite SDK implementation, see the Quickstart Guide for detailed instructions on how to properly integrate the SDK into your project. 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 enrollment capability.

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 customer session

To start the enrollment process, you need to provide the customer_session. First, you need to create a customer. Use the Create Customer endpoint to create new customers. In the response, you will receive the customer id, which you use to create the customer session. After creating the customer, you can create the customer session. Use the customer id and the Create Customer Session endpoint. The customer_session will be provided in the response. You need a new customer_session every time you enroll in a new payment method.

Step 4: Start the enrollment process

Use the configuration below to provide a lite and user-friendly enrollment experience for your customers:

await yuno.mountEnrollmentLite({
  customerSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  renderMode: {
    type: "element",
    elementSelector: "#root",
  },
  countryCode: "US",
  language: "en",
  showLoading: true,
  issuersFormEnable: true,
  onLoading: (args) => console.log(args),
  card: {
    type: "extends",
    styles: "",
    texts: {},
  },
  texts: {},
  enrollmentStatus(data) {
    console.log("Enrollment status:", data);
  },
  async error(error, data) {
    console.error("An error occurred:", error);
    await yuno.hideLoader();
  },
});

When using mountEnrollmentLite, specify the callbacks to handle enrollment. You can also customize the interface using the texts objects.

Parameters

Configure the lite enrollment with the following options:

Parameter	Description
`customerSession`	Refers to the current enrollment’s customer session.
`elementSelector`	The HTML element where the enrollment form renders. Pass it inside `renderMode: { type: "element", elementSelector }`; a top-level `elementSelector` is ignored and the form opens as a modal.
`countryCode`	This parameter specifies the country code for which the enrollment is being set up.
`language`	Language for enrollment forms.
`showLoading`	Controls the visibility of the Yuno loading/spinner page during the enrollment process.
`onLoading`	Required to receive notifications about server calls or loading events during the enrollment process.
`issuersFormEnable`	Enables the issuer’s form (for example, a list of banks).
`card`	Defines the configuration for the card form.
`texts`	Allows you to set custom button texts.
`enrollmentStatus`	Callback invoked when the enrollment process finishes. Receives `{ vaultedToken, status }`.
`error`	Callback invoked when there is an error in the enrollment process.
`onChange`	Reports whether the enrollment form is complete. Receives `{ form: { isValid } }`. Available since v1.10.11.

Status ValuesCommon status values include ENROLLED, DECLINED, CANCELED, and ERROR.

PayPal enrollment with element render mode

Available from Web SDK 1.10.13.

By default, mountEnrollmentLite opens the Yuno modal for PayPal enrollment. The shopper clicks your PayPal button, sees the modal, and has to click PayPal a second time. With element render mode the PayPal button renders directly on your page, and the shopper completes the enrollment in one click.

How it works

Add an empty container to your page, then pass renderMode: { type: 'element', elementSelector } to mountEnrollmentLite. The SDK renders the real PayPal button inside that container and shows a loading skeleton until PayPal finishes loading. The PayPal button replaces your own button — do not place your button in front of it. If you do not pass renderMode, the modal behavior stays exactly as before.

Integration steps

Remove your existing PayPal button.
Add an empty <div> where the PayPal button should appear.
Pass renderMode with type: 'element' and an elementSelector pointing at that <div>.

<div id="paypal-enrollment"></div>

await yuno.mountEnrollmentLite({
  customerSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  countryCode: "US",
  language: "en",
  renderMode: {
    type: "element",
    elementSelector: "#paypal-enrollment",
  },
  enrollmentStatus(data) {
    console.log("Enrollment status:", data);
  },
  error(error, data) {
    console.error("An error occurred:", error);
  },
});

The button takes 100% of the container width unless you set width.

Customizing the PayPal button

Optional. Pass externalButtons.paypal to mountEnrollmentLite to style the button, using the same properties as the PayPal express button in checkout. The defaults differ from checkout, so they are listed in full below.

await yuno.mountEnrollmentLite({
  customerSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  countryCode: "US",
  language: "en",
  renderMode: {
    type: "element",
    elementSelector: "#paypal-enrollment",
  },
  externalButtons: {
    paypal: {
      color: "blue",
      shape: "pill",
      label: "paypal",
      height: 48,
      width: 300,
      locale: "en_US",
    },
  },
  // ... rest of config
});

Property	Type	Default	Description
`color`	`'gold'` \| `'blue'` \| `'silver'` \| `'white'` \| `'black'`	PayPal decides	Button background color
`shape`	`'rect'` \| `'pill'` \| `'sharp'`	`'rect'`	Button shape
`label`	`'paypal'` \| `'checkout'` \| `'buynow'` \| `'pay'` \| `'installment'`	PayPal decides	Button label text
`height`	`number`	`48`	Button height in px (valid range: 25–55)
`width`	`number`	100% of the container	Wrapper width in px
`locale`	`string`	PayPal decides from the shopper’s browser	Button language, in PayPal’s `language_COUNTRY` format (for example `en_US`, `es_ES`, `pt_BR`). See PayPal’s supported locales.

Result

The shopper clicks the PayPal button, approves in the PayPal popup, and the SDK completes the enrollment.
enrollmentStatus receives the vaultedToken with status ENROLLED.
If the shopper closes the popup, error receives CANCELED_BY_USER.

KCP KakaoPay and PAYCO enrollment (Web)

KakaoPay desktop enrollment and KCP mobile POST redirects are available from Web SDK 1.11.27. PAYCO desktop enrollment is supported from Web SDK 1.11.43.

Yuno Lite Web SDK supports KakaoPay (KAKAO_PAY) and PAYCO (KCP_PAYCO) enrollment via KCP on desktop browsers, as well as automatic HTTP POST form redirects for KCP enrollment on mobile browsers.

Desktop enrollment flow

On desktop browsers, KakaoPay and PAYCO enrollments render an action button inside the lite enrollment component.

How it works

Script loading & callback setup: When the enrollment component mounts, the SDK declares the KCP callback handler (window.m_Completepayment), then verifies and loads KCP’s script bundle from script_url (https://*.kcp.co.kr).
User action: The shopper clicks the action button. The SDK prepares the order form and opens the KCP authorization window (KCP_Pay_Execute_Web).
Completion & submission: When the shopper finishes in KCP, KCP calls the SDK’s callback with the result (res_cd, res_msg, enc_data, enc_info, tran_cd), and the SDK posts it to the backend result_url (https://*.y.uno or your white-label API host) using a hidden form submission. When configured with RENDER_POPUP, the POST submission occurs within the popup rather than navigating the parent page.
Cleanup: Unmounting the enrollment component closes any open KCP window and restores any pre-existing window.m_Completepayment handler.

Button states and error recovery

Button disabled: If required backend enrollment configuration (script_url, form_fields, or result_url) is missing or targets an unauthorized host, the button is disabled and displays an inline error message.
Script load retry: If KCP scripts fail to load, the button shows an inline error; clicking it loads KCP again, and once loaded, the next click opens KCP.
Dismissed popup recovery: If the shopper closes the KCP popup without approving, the SDK detects layer removal via DOM mutation observers and re-enables the button for another attempt.
Timeout recovery: If the browser remains on the page 10 seconds after posting the enrollment result (typically caused by missing CSP form-action policies blocking form submission), the SDK clears the processing state, shows an inline error and re-enables the button so the shopper can retry. Notice that no merchant error callback is fired.

KCP mobile POST redirect

When enrolling via KCP on mobile browsers, the backend returns a require_action.redirect payload with method: "POST" and init_url targeting a KCP host (*.kcp.co.kr). The Lite Web SDK automatically detects the POST redirect configuration, builds a hidden form populated with form_fields, appends it to the DOM, and submits the form to navigate the user directly to the provider.

Content Security Policy (CSP) requirements

If your website enforces a strict Content Security Policy (CSP), configure the following directives to allow the KCP scripts, iframe overlays, and form submissions:

Directive	Allowed sources	Description
`script-src`	`https://*.kcp.co.kr`	Allows loading KCP SDK hub and helper scripts (`kcp_spay_hub.js`, `kcp_jquery`, etc.).
`frame-src`	`https://*.kcp.co.kr`	Allows rendering the KCP overlay modal and payment iframe.
`form-action`	`https://.kcp.co.kr https://.y.uno`	Allows hidden form POST navigation to KCP and posting the enrollment result to Yuno (or your white-label API domain).

Missing form-action directives for *.y.uno or *.kcp.co.kr will cause browser-level form submission blocks without JavaScript errors, resulting in the enrollment timing out.

Step 5: Initiate the enrollment (Required)

After mounting the SDK using await yuno.mountEnrollmentLite(), the form will be displayed in the specified element. The user can then proceed with entering their payment method details to complete the enrollment.

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).

Error handling

Handle errors returned by the SDK in your app, such as failed enrollment 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 customer session

Step 4: Start the enrollment process

Parameters

PayPal enrollment with element render mode

How it works

Integration steps

Customizing the PayPal button

Result

KCP KakaoPay and PAYCO enrollment (Web)

Desktop enrollment flow

How it works

Button states and error recovery

KCP mobile POST redirect

Content Security Policy (CSP) requirements

Step 5: Initiate the enrollment (Required)

Error handling

Stay updated

​Step 1: Include the library in your project

​Step 2: Initialize SDK with the public key

​Step 3: Create a customer session

​Step 4: Start the enrollment process

​Parameters

​PayPal enrollment with element render mode

​How it works

​Integration steps

​Customizing the PayPal button

​Result

​KCP KakaoPay and PAYCO enrollment (Web)

​Desktop enrollment flow

​How it works

​Button states and error recovery

​KCP mobile POST redirect

​Content Security Policy (CSP) requirements

​Step 5: Initiate the enrollment (Required)

​Error handling

​Stay updated

Step 1: Include the library in your project

Step 2: Initialize SDK with the public key

Step 3: Create a customer session

Step 4: Start the enrollment process

Parameters

PayPal enrollment with element render mode

How it works

Integration steps

Customizing the PayPal button

Result

KCP KakaoPay and PAYCO enrollment (Web)

Desktop enrollment flow

How it works

Button states and error recovery

KCP mobile POST redirect

Content Security Policy (CSP) requirements

Step 5: Initiate the enrollment (Required)

Error handling

Stay updated