Implementación Full SDK (Web)

Esta página proporciona una guía paso a paso para implementar y habilitar la funcionalidad Full Web SDK de Yuno en tu aplicación.

📘

Referencia del registro de cambios:

Esta guía cubre la versión actual del SDK. Para más información sobre versiones anteriores, consulte el registro de cambios.

Paso 1: Incluya la biblioteca en tu proyecto

Añade la siguiente etiqueta script a tu archivo HTML para incluir el Yuno Web SDK:

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

Alternativamente, puedes instalarlo a través de npm:

npm install @yuno-pagos/sdk-web

Una vez completada la integración del SDK, siga los siguientes pasos para implementar la funcionalidad de pago completa.

📘

Biblioteca de TypeScript

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

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

Crear una instancia de Yuno proporcionando un PUBLIC_API_KEY. Ver el credenciales para más información.

Initialize el SDK con tu clave pública de API:

const yuno = await YunoinitializePUBLIC_API_KEY);

Paso 3: Iniciar el proceso de pago

Use el endpoint yuno.startCheckout para iniciar el proceso de pago con los parámetros necesarios.

Mire la Tabla de parámetros para conocer todas las opciones que puede utilizar con startCheckout.

Para más personalización o ajustes avanzados/opcionales, consulte la sección Funciones complementarias.

Parámetros

La siguiente tabla enumera todos los parámetros disponibles para el startCheckout con descripciones:

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);
  },
  yunoPaymentMethodSelected: () => {
    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 });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘

Modo de renderizado

Por defecto, el SDK de Yuno se muestra como un modal. Sin embargo, puedes especificar el elemento donde se renderizará el SDK. Para más información, accede al Modo de renderizado en la página de características complementarias.

📘

onPaymentMethodSelected Evento

Para todas las APM, incluidas Google Pay, Apple Pay y PayPal, onPaymentMethodSelected se activa en cuanto el cliente elige el método de pago (antes de que comience el flujo de pago). Definir onPaymentMethodSelected en el startCheckout antes mountCheckout.

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

📘

Pantalla de Google Pay y Apple Pay

A partir de la versión 1.5 del SDK, Google Pay y Apple Pay aparecen como botones directos en lugar de botones de opción en la lista de métodos de pago . Se muestran por separado de otros métodos de pago .

Paso 4: Monte el SDK

Mostrar los métodos de pago:

yunomountCheckout();

Montar con un método de pago por defecto seleccionado:

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

Paso 5: Iniciar el proceso de pago

Llamar yuno.startPayment() para iniciar el flujo de pago después de que el usuario selecciona un método de pago:

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

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

Paso 6: Obtener el OTT ( token de un solo uso)

Después de que el cliente rellene 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 yuno.CreatePayment(oneTimeToken) se activa con el token de un solo uso.

yunoCrearPagooneTimeToken);

También puedes usar tokenWithInformation para recibir información adicional proporcionada por el cliente en el proceso de pago, como los plazos o el 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 7: Crear el pago

Una vez completados los pasos anteriores, proceda a crear un pago. La creación de un pago consecutivo debe realizarse utilizando el endpoint Create Payment . El backend del comerciante debe llamar a este endpoint para crear el pago en Yuno utilizando el token de un solo uso y la sesión de pago.

📘

Completar la integración

Tras el paso 7, habrá implementado correctamente el flujo de pago básico. Para probar su integración, cree un pago de prueba utilizando la sesión de pago y token de un solo uso. Para obtener información sobre funciones adicionales y configuraciones avanzadas, consulte la sección Funciones complementarias.

❗️

ContinuePaymentmethod

Después de crear un pago, Yuno requiere para que usted integre el continuePayment del SDK. Esto es necesario porque algunos métodos de pago asincrónicos requieren acciones adicionales del cliente para completar el proceso. La respuesta de la API indicará este escenario configurando sdk_action_required campo a verdadero. Cuando esto ocurre, debes llamar yuno.continuePayment(), que presentará automáticamente las pantallas necesarias al cliente, permitiéndole completar el flujo de pago sin necesidad de manejar cada caso manualmente.

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() devuelve un objeto con la siguiente estructura o null:

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

Cuando el método devuelve un objeto, puede gestionar los flujos de pago de tu aplicación que requieran una gestión de redireccionamiento personalizada. Cuando devuelve null, no es necesaria ninguna acción adicional por parte 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:

• Montar botones externos
• Cargador de formularios
• Modo de renderizado
• Configuraciones de tarjeta
  • Guardar tarjeta para futuros pagos
  • Modos 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

Puedes utilizar la mountExternalButtons para mostrar los botones de Google Pay y Apple Pay en ubicaciones personalizadas dentro de tu interfaz de usuario. Esto te permite controlar dónde se muestran estos botones.

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();

Cargador de formularios

Controla el uso de la pala cargadora:

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

Formulario del emisor

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

Modo de renderizado

yuno.startCheckout({
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

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

Puede mostrar una casilla de verificación para guardar o inscribir tarjetas utilizando cardSaveEnable: true. En los siguientes ejemplos se muestra la casilla de verificación para ambas variantes de representación del formulario de tarjeta:

Modos de renderizado

Las siguientes capturas de pantalla muestran la diferencia entre:

• 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

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. Si se rechaza la transacción:
   1. Ejecutar el método yuno.notifyError() para borrar el CVV introducido previamente 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 de pago

Puede ocultar el botón Pagar al presentar el formulario de datos de la tarjeta o del cliente. Establecer showPayButton a false al iniciar la comprobación con el startCheckout función:

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

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

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

Si oculta el botón Pagar, deberá 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, llame a la función submitOneTimeTokenForm función:

yuno.submitOneTimeTokenForm();

Inicialización opcional options parámetro

Esta función opcional está pensada para casos de uso avanzado en los que necesite personalizar cómo se gestiona la identificación del dispositivo a través de las cookies.

A partir de Yuno SDK v1.2, la función Yuno.initialize La función admite un nuevo parámetro opcional llamado optionsEsto permite una configuración avanzada, como personalizar el nombre de la cookie utilizada para la identificación del dispositivo.

Opciones de inicialización

La firma de función actualizada es:

const yuno = await Yunoinitialize(publicApiKey, applicationSession, opciones);

• publicApiKey (string): Su clave API pública.
• applicationSession (string | undefined): ID de sesión opcional.

  Recomendación: Deja esto como está undefined Para que el SDK pueda generar y gestionar su propia sesión internamente. Configure esta opción solo si necesita una estrategia de gestión de sesiones personalizada.

• options (object | undefined): Objeto opcional para configuración avanzada.

Estructura de opciones

El objeto options admite la siguiente estructura:

const options = {
  cookies: {
    deviceId: {
      name: "customCookieName",
    },
  },
};

Si el deviceId.name no se especifica, el SDK tiene como valor predeterminado "yuno" como el nombre de la cookie.

Ejemplo de implementación

const publicApiKey = "your-public-api-key";
const options = {
  cookies: {
    deviceId: {
      name: "custom-device-id",
    },
  },
};

const yuno = await Yuno.initialize(publicApiKey, undefined, options);

¿Qué sigue?

Conoce las configuraciones adicionales del Full SDK accediendo a Funciones Complementarias. También puedes acceder a otras funciones disponibles en el SDK Web de Yuno:

• Personalizaciones del SDK: Cambia la apariencia del SDK para que se adapte a tu marca
• Estado delpago : Actualiza al usuario sobre el proceso de pago
• SDK de instalación de 3DS: Integre 3DS en su flujo de pago

Mantente al día

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