Lite SDK (Inscripción Web)

👍

SDK recomendado

Recomendamos utilizar el Seamless SDK Web para una integración sin problemas. Esta opción ofrece una solución de pago flexible con componentes de interfaz de usuario predefinidos y opciones de personalización.

Siga esta guía paso a paso para implementar y habilitar la funcionalidad de inscripción de Lite Web SDK de Yuno en su aplicación.

Paso 1: Incluya la biblioteca en tu proyecto

Antes de proceder con la implementación Lite SDK , consulte la Descripción general de la integración del SDK para obtener instrucciones detalladas sobre cómo integrar correctamente el SDK en su proyecto.

La guía de integración ofrece tres métodos flexibles:

• Método 1 (HTML): Añade una única etiqueta script a tu archivo HTML. Este es el método más sencillo, ideal para implementaciones básicas y prototipos rápidos
• Método 2 (JavaScript dinámico): Cargue el SDK mediante programación con gestión de errores y estados de carga personalizados. Mejor para aplicaciones que necesitan más control sobre la integración.
• Método 3 (NPM): Utilice nuestro paquete NPM en aplicaciones JavaScript modernas. Este es nuestro enfoque recomendado, con gestión de dependencias, agitación de árboles y compatibilidad con TypeScript

1. Agregue el script del SDK directamente en HTML

La forma más sencilla de integrar el SDK de Yuno es agregando una etiqueta <script> a tu archivo HTML. Este método proporciona una implementación rápida, manteniendo una carga asíncrona adecuada. El SDK expone un evento que notifica cuando está completamente cargado, lo que garantiza que puedas inicializar y usar sus funciones de forma segura en el momento adecuado.

En primer lugar, configure el receptor de eventos y, a continuación, cargue el SDK:

<script>
  window.addEventListener('yuno-sdk-ready', () => {
    console.log('SDK loaded');
    const yuno = await Yuno.initialize(PUBLIC_API_KEY);
  });
</script>

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

2. Inyectar el SDK dinámicamente usando JavaScript

El método de inyección dinámica de JavaScript proporciona un mayor control sobre la carga e inicialización del SDK. Este enfoque permite:

• Cargue el SDK programáticamente cuando sea necesario
• Implementar estados de carga personalizados y manejo de errores
• Controle con precisión cuándo estará disponible el SDK
• Sincronice la inicialización del SDK con la lógica de tu aplicación
• Cree un manejo de errores personalizado para su caso de uso

Este método es ideal cuando necesita un control granular sobre el proceso de carga del SDK y desea manejar varios escenarios con precisión.

Crear una función para inyectar el SDK dinámicamente:

export const injectScript = async (): Promise<boolean> => {
  const head = document.getElementsByTagName('head')[0];
  const js = document.createElement('script');
  js.src = "https://sdk-web.y.uno/v1.5/main.js";
  js.defer = true;

  return new Promise((resolve, reject) => {
    window.addEventListener('yuno-sdk-ready', () => {
      resolve(true);
    });

    js.onerror = (error) => {
      const event = new CustomEvent('yuno-sdk-error', { detail: error });
      window.dispatchEvent(event);
      reject(new Error(`Failed to load script: ${js.src} - ${error.message}`));
    };

    head.appendChild(js);
  });
};

Utiliza la función para inyectar el SDK:

await injectScript();
const yuno = await YunoinitializePUBLIC_API_KEY);

3. Utiliza el módulo NPM

Para proyectos que utilizan la gestión de paquetes de NPM, puede instalar el SDK como módulo a través de NPM. Este enfoque proporciona una mejor gestión de dependencias, control de versiones e integración fluida con herramientas y frameworks de compilación de JavaScript modernos. Resulta especialmente beneficioso para aplicaciones que utilizan empaquetadores como webpack, Rollup o Vite.

npm install @yuno-pagos/sdk-web

Luego, cargue e inicialice el SDK de la siguiente manera:

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

await loadScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Elija el método de integración que mejor se adapte a su flujo de trabajo de desarrollo y requisitos técnicos. Tras completar la integración del SDK, puede continuar con los siguientes pasos para implementar la función de inscripción ligera.

📘

Biblioteca de TypeScript

Si estás usando TypeScript, Yuno proporciona una librería que puedes usar para ver todos los métodos disponibles en Yuno Web SDK.

Paso 2: Initialize el SDK con la clave pública

En su aplicación JavaScript, cree una instancia del archivo Yuno proporcionando un PUBLIC_API_KEY. Consulte la página Obtenga sus credenciales de API si no tienes tus credenciales. En el siguiente ejemplo, la clase inicializada se atribuye a la constante yunoconstante.

const yuno = await YunoinitializePUBLIC_API_KEY);

Paso 3: Crear una sesión de cliente y un objeto de método de pago de inscripción

Antes de continuar con el proceso, tendrás que crear una sesión de cliente y un objeto de método de pago para utilizarlos en la configuración de tu integración SDK Lite para la inscripción. Al crear el objeto de método de pago , tendrás que definir qué método de pago va a estar disponible para que tu cliente se inscriba.

📘

Importante

La sesión de cliente y el objeto de método de pago de inscripción deben crearse en tu servidor para mantener seguras tus claves API privadas. El tipo de método de pago se establece en el lado del servidor, a diferencia de otras integraciones en las que puede establecerse en el lado del cliente.

Ejemplo del lado del servidor

Crea una sesión de cliente y un método de pago inscripción en tu backend. Esto mantiene seguras tus claves API privadas.

// 1. Create customer session
const customerSession = await fetch(
  "https://api-sandbox.y.uno/v1/customers/sessions",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${PRIVATE_SECRET_KEY}`,
    },
    body: JSON.stringify({
      customer_id: "your-customer-id",
      country: "US",
    }),
  }
).then((res) => res.json());

// 2. Create enrollment payment method
const enrollment = await fetch(
  `https://api-sandbox.y.uno/v1/customers/sessions/${customerSession.id}/payment-methods`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${PRIVATE_SECRET_KEY}`,
    },
    body: JSON.stringify({
      type: "CARD",
    }),
  }
).then((res) => res.json());

// Return customerSession to your client
return customerSession;

Ejemplo del lado del cliente

Tras recibir el customerSession de tu servidor, initialize el SDK de Yuno y monta el formulario de inscripción en el lado del cliente.

// Initialize Yuno SDK
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

// Mount the enrollment form
yuno.mountEnrollmentLite({
  customerSession, // Received from your server
  countryCode: "US",
  language: "en",
  showLoading: true,
  onLoading: (args) => {
    console.log(args);
  },
});

📘

Verificar

En caso de que desee verificar tarjetas (autorización de valor cero) antes de la inscripción, puede completar el verify struct mientras define el objeto de método de pago para la sesión del cliente.

Paso 4: montar la inscripción lite

La configuración y el montaje se realizan en el mismo paso para Registro Lite. Para hacerlo, utiliza el yuno.mountEnrollmentLite y proporciona los parámetros necesarios. La siguiente tabla enumera todos los parámetros y sus descripciones.

El siguiente bloque de código presenta un ejemplo de configuración y montaje de parámetros de Registro Lite.

yuno.mountEnrollmentLite({
  customerSession: 'e15648b0-fcd5-4799-a14c-cc463ae8a133',
  /**
   * The complete list of country codes is available on https://docs.y.uno/docs/country-coverage-yuno-sdk
   */
  country_code: country,
  /**
  * Language for payment forms (see Supported languages)
  * Defaults to browser language when available
  */
  language: 'en-US',
  /**
   * Hide or show the Yuno loading/spinner page
   * Default is true
   * @optional
   */
  showLoading: true,
  /**
   * Required if you'd like to be informed if there is a server call
   * @param { isLoading: boolean, type: 'DOCUMENT' | 'ONE_TIME_TOKEN'  } data
   * @optional
   */
  onLoading: (args) => {
    console.log(args);
  }
  /**
   *  API card
   *  @optional
   */
  card: {
    /**
     * Mode render card can be step or extends
     * Default extends
     */
    type: "extends",
    /**
     * Write custom CSS to style the card form. Your CSS will be injected into the iframe.
     * Example:
     * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap');
     *  .Yuno-front-side-card__name-label {
     *    color: red !important;
     *    font-family: 'Luckiest Guy' !important;
     *   }`
     */
    styles: '',
    /**
     * Show checkbox for save/enroll card
     * Default is false
     */
    cardSaveEnable: false,
    /**
     * Custom texts in Card forms buttons
     * Example:
     *
     *  texts: {
     *    cardForm?: {
     *      enrollmentSubmitButton?: string;
     *       paymentSubmitButton?: string;
     *     }
     *     cardStepper?: {
     *       numberCardStep?: {
     *         nextButton?: string;
     *       },
     *       cardHolderNameStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       },
     *       expirationDateStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       },
     *       cvvStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       }
     *     }
     *  }
     */
    texts: {},
    /**
     * Hide or show the document fields into card form
     * Default is true
     * @optional
     */
    documentEnable: true,
  },
  /**
   * Call back is called with the following object
   * @param {{
   *  status: 'CREATED'
   *    | 'EXPIRED',
   *    | 'REJECTED',
   *    | 'READY_TO_ENROLL',
   *    | 'ENROLL_IN_PROCESS',
   *    | 'UNENROLL_IN_PROCESS',
   *    | 'ENROLLED',
   *    | 'DECLINED',
   *    | 'CANCELED',
   *    | 'ERROR',
   *    | 'UNENROLLED',
   *  vaultedToken: string,
   * }}
   */
  yunoEnrollmentStatus: ({ status, vaultedToken}) => {
    console.log('status', { status, vaultedToken})
  },
  /**
   * If this is called the SDK should be mounted again
   * @param { error: 'CANCELED_BY_USER' | any }
   * @optional
   */
  yunoError: (error) => {
    console.log('There was an error', error)
  },
});

continuePayment valor de retorno o nulo

Para los métodos de pago que requieren una acción del lado del comerciante (por ejemplo, cuando el proveedor de pagos requiere una URL de redireccionamiento en una vista web), await yuno.continuePayment() El método devolverá un objeto con la siguiente estructura o nulo:

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

Cuando el método devuelve un objeto, permite gestionar los flujos de pago de la aplicación que requieren una gestión de redirecciones personalizada. Si devuelve un valor nulo, no se requiere ninguna acción adicional del comerciante.

📘

App Demo

Además de los ejemplos de código proporcionados, puedes acceder a la Demo App para una implementación completa de los SDK de Yuno. La demo app incluye ejemplos de trabajo de todos los SDK de Yuno y puede ser clonada desde el repositorio de GitHub.

Características complementarias

Yuno Web SDK proporciona servicios y configuraciones adicionales que puede utilizar para mejorar la experiencia de los clientes:

• Loader
• Modo de representación de formularios
• Configuración del formato de tarjeta
  • Botón de formulario de pago de texto
• Personalización del SDK

Loader

Controla el uso de la pala cargadora.

yuno.startCheckout({
  showLoading: true,
});

Modo de representación de formularios

yuno.startCheckout({
  renderMode: {
    /**
     * Type can be one of `modal` or `element`
     * By default the system uses 'modal'
     * It is optional
     */
    type: "modal",
    /**
     * Element where the form will be rendered.
     * It is optional
     * Can be a string (deprecated) or an object with the following structure:
     * {
     *   apmForm: "#form-element",
     *   actionForm: "#action-form-element"
     * }
     */
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

A continuación, encontrará capturas de pantalla que presentan la diferencia entre los modos de renderizado. modal y elements para ver la lista de métodos de pago.

También puede elegir una de las opciones de renderizado para el formulario de la tarjeta, step y extends:

Configuraciones de tarjeta

yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    texts: {},
  },
});

Botones del formulario de pago por texto

yuno.startCheckout({
  texts: {
    customerForm?: {
      submitButton?: string;
    }
    paymentOtp?: {
      sendOtpButton?: string;
    }
  }
})

Personalizaciones del SDK

Utilice las personalizaciones del SDK  para cambiar su aspecto y adaptarlo a su marca.

Mantente al día

Visita el registro de cambios para ver las últimas actualizaciones del SDK y el historial de versiones.