Lite SDK (Pago Web)

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

Paso 1: Incluya la biblioteca en tu proyecto

Asegúrese de que el archivo SDK de Yuno esté incluido en su página web antes de cerrar el </body> . Consulte el siguiente ejemplo:

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

📘

Compatibilidad con 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 .

Como en el ejemplo siguiente, utiliza la clase inicializada que se atribuye a la clase yunoconstante.

const yuno = await YunoinitializePUBLIC_API_KEY);

Paso 3: Iniciar el proceso de pago

Comenzarás el proceso de pago. Para hacerlo, utiliza el yuno.startCheckout y proporciona los parámetros necesarios.

La siguiente tabla enumera todos los parámetros obligatorios y sus descripciones. Para los parámetros opcionales, vaya a Características complementarias.

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);
  },
  async yunoCreatePayment(oneTimeToken) {
    /**
     * The createPayment function calls the backend to create a payment in Yuno.
     * It uses the following endpoint https://docs.y.uno/reference/create-payment
     */
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘

Tipos de transacciones

Los pagos pueden ser iniciados por el cliente (CIT) o por el comerciante (MIT). Encontrará más información sobre sus características en Credenciales almacenadas.

El paso a paso presentado en esta página se refiere a una transacción iniciada por el cliente sin la opción de recurrencia. Normalmente, se utiliza en compras únicas en línea, compras en tiendas, retiros en cajeros automáticos, etc.

Paso 4: Monte el SDK

A continuación, tienes que montar el SDK, presentando el pago basado en el método de pago seleccionado por tu cliente. Recuerde, cuando se utiliza el Lite SDK, usted es responsable de mostrar los métodos de pago y capturar la selección del cliente. Acceda a Lite SDK (pago) para obtener información adicional.

Use el endpoint yuno.mountCheckoutLite() seleccionando un elemento HTML y usando un selector CSS válido (#, ., [data-*]) para mostrar el pago del método de pago seleccionado.

yuno.mountCheckoutLite({
  /**
   * can be one of 'PAYPAL' | 'PIX' | CARD
   */
  paymentMethodType: PAYMENT_METHOD_TYPE,
  /**
   * Vaulted token related to payment method type.
   * Only if you already have it
   * @optional
   */
  vaultedToken: VAULTED_TOKEN,
});

Después de montar el SDK, el flujo del método de pago seleccionado se iniciará automáticamente.

En el caso de PayPal, la pago de PayPal se abre ahora inmediatamente después de que el comprador selecciona PayPal, sin necesidad de hacer clic para confirmar.

📘

Google Pay y Apple Pay en Lite SDK

Google Pay y Apple Pay no están disponibles como opciones de pago integradas en el Lite SDK. Para utilizar estos métodos de pago , debes utilizar la opción mountExternalButtons método. Consulta Montar botones externos para más información.

Paso 5: Montar botones externos (Opcional)

Si quieres utilizar Google Pay o Apple Pay en el Lite SDK, puedes montar estos botones de pago externamente utilizando el botón mountExternalButtons método. Este método te permite elegir dónde se muestra cada botón en tu IU.

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

El objeto mountExternalButtons acepta una matriz de objetos, cada uno de los cuales contiene:

• paymentMethodType: Cualquiera 'APPLE_PAY' o 'GOOGLE_PAY'
• elementSelector: El selector CSS del elemento HTML donde debe mostrarse el botón

Desmontar botones externos

Puedes desmontar un solo botón externo:

yuno.desmontarBotónExterno('APPLE_PAY');

O desmonta todos los botones externos a la vez:

yuno.unmountAllExternalButtons();

Paso 6: Iniciar el proceso de pago

Después de que el usuario haya seleccionado un método de pago, recuerde llamar a yuno.startPayment() para iniciar el flujo de pago. A continuación encontrará un ejemplo donde yuno.startPayment() se llama cuando el usuario hace clic en button-pay:

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

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

Paso 7: Consigue el OTT (token de un solo uso)

Una vez que el cliente rellena los datos solicitados en los formularios de pago de Yuno, el SDK proporciona el token de un solo uso. La función de configuración yunoCreatePayment(oneTimeToken) se activa con el token de un solo uso.

yunoCrearPagooneTimeToken);

También puedes usar tokenWithInformation para recibir cualquier información adicional que el cliente proporcione al finalizar la compra, como cuotas o tipo/número de documento.

yunoCrearPagooneTimeToken, tokenConInformación);

📘

Gestión del cargador

El comerciante es responsable de gestionar el cargador. Yuno ofrece una opción de cargador predeterminada, pero los comerciantes pueden implementar su propio cargador si lo prefieren. En ese caso, son responsables de realizar las configuraciones necesarias.

Paso 8: Crea el pago

Una vez que haya completado los pasos descritos anteriormente, podrá crear un pago. La creación del pago consecutivo debe realizarse utilizando el endpoint Create Payment . El comerciante debe llamar a su backend para crear el pago dentro de Yuno, utilizando el token de un solo uso y la sesión de pago.

📘

Continuar con el método de pago

Yuno recomienda integrar el continuePayment del SDK después de crear el pago. Esto se debe a que ciertos métodos de pago asíncronos requieren una acción adicional por parte del cliente para completar el pago. La API le informará de este escenario a través del método sdk_action_required de la respuesta, que se devolverá como verdadero. La yuno.continuePayment() mostrará pantallas adicionales a los clientes, donde podrán realizar las acciones necesarias para completar el pago. Si sdk_action_required es falso, este paso no es necesario.

Características complementarias

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

• Montar botones externos
• Cargador de formularios
• Lista de emisores bancarios
• Modo de renderizado
• Configuraciones de tarjeta
  • Guardar tarjeta para futuros pagos
  • Modo de renderizado
  • Botones del formulario de pago por texto
  • Formulario de tarjeta de crédito persistente para reintentar pagos
  • Ocultar botón Pagar

Montar botones externos

Use el endpoint mountExternalButtons para mostrar los botones de Google Pay y Apple Pay en tu interfaz personalizada. Este método es necesario si quieres utilizar estos métodos de pago en Lite SDK, ya que no están disponibles como opciones de pago integradas.

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

Parámetros

Botones de desmontaje

Puedes desmontar un solo botón externo mediante el tipo de método de pago :

yuno.desmontarBotónExterno('APPLE_PAY');

O desmonta todos los botones externos a la vez:

yuno.unmountAllExternalButtons();

Loader

Controla el uso de la pala cargadora.

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

Forma del emisor

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

Modo de representación de formularios

📘

Modo de renderizado mejorado en Lite SDK v2.0

El Lite SDK v2.0 mejorado proporciona capacidades avanzadas de modo de renderizado que incrustan los formularios de pago de Yuno directamente en su interfaz. Esto le da un control completo sobre el proceso de pago, incluyendo la carga, el estado y las pantallas de entrada de pago, con una personalización visual completa y una integración UX perfecta.

yuno.startCheckout({
  renderMode:

Configuraciones de tarjeta

yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    cardSaveEnable: false,
    texts: {},
    cardNumberPlaceholder: "Enter card number", // Optional: Custom placeholder text
    hideCardholderName: false, // Optional: Set to true to hide cardholder name field
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
});

Guardar tarjeta para futuros pagos

Además, puede mostrar una casilla de verificación para guardar o inscribir tarjetas mediante la función cardSaveEnable: true. A continuación se muestran ejemplos de la casilla de verificación para ambos renders de formulario de tarjeta.

Modos de renderizado

A continuación encontrará capturas de pantalla en las que se presenta la diferencia entre lo siguiente:

• Modos de renderizado modal y elements para la lista de métodos de pago
• Modos de renderizado step y extends para el formulario de la tarjeta de crédito

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

Botones del formulario de pago por texto

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

Formulario de tarjeta de crédito persistente para reintentar pagos

Si se rechaza una transacción, puede utilizar el formulario de tarjeta de crédito para reintentar un pago después de que el cliente haya introducido los datos de la tarjeta de crédito. Para ello, deberá:

1. Añada el siguiente parámetro al inicializar el SDK para que persista el formulario de tarjeta de crédito una vez creado el token de un solo uso:
   JavaScript

   yuno.startCheckout({
     automaticallyUnmount: false,
   });

2. En caso de que la transacción sea rechazada, deberá:
   1. Ejecutar el método yuno.notifyError() para borrar el CVV introducido anteriormente para la primera transacción.
   2. Cree una nueva sesión de pago y actualice el SDK con la nueva ejecutando yuno.updateCheckoutSession(checkoutsession)
3. Continúe con el nuevo pago y el token de un solo uso con el flujo de pago habitual.

Ocultar botón Pagar

Puedes ocultar el Paga al presentar los Formularios de Datos de la Tarjeta o del Cliente. Para controlar esta función, establecerás showPayButton a false al iniciar la comprobación con el startCheckout . El siguiente bloque de código presenta un ejemplo de cómo ocultar el botón de pago:

yuno.startCheckout({
  /**
   * Hide (false) or show (true) the customer or card form pay button
   * @default true
   * @optional
   */
  showPayButton: false,
});

Las siguientes imágenes presentan ejemplos del Formulario de Datos del Cliente con y sin el botón Pagar:

Las siguientes imágenes presentan ejemplos del Formulario de Tarjeta con y sin el botón Pagar:

Si ocultas el botón Paga tendrás que iniciar la creación del token de un solo uso a través de tu código. Para crear el token de un solo uso y continuar el pago en tu backend, llama a la función submitOneTimeTokenForm función. El siguiente bloque de código muestra cómo utilizar la función submitOneTimeTokenForm .

/**
 * Esta función activa la misma funcionalidad que se llama cuando el cliente hace clic en el botón del formulario de pago. Este enfoque no funciona si usted eligió paso para el modo de representación.
 */
yuno.submitOneTimeTokenForm();

Mantente al día

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