SDK web

Utiliza el SDK de DEUNA para renderizar el Widget de Pago, el Vault de Pago, Click to Pay, billeteras nativas, cupones y acciones posteriores en un modal o dentro de una página. El SDK del navegador se distribuye como un script clásico a través del CDN de DEUNA.

Cargar el SDK#

Asegúrate de utilizar la versión del SDK que estás utilizando en tu integración. Prueba una versión más reciente en el entorno de pruebas antes de cambiar esta URL en producción.

<script
  crossorigin
  src="https://cdn.deuna.io/web-sdk/v1.7/index.js">
</script>

El script expone el singleton window.DeunaSDK. También admite DeunaSDK.newInstance() cuando una página necesita instancias del SDK aisladas.

Inicialización#

Inicializa una vez con la clave API pública para el entorno seleccionado. Define el entorno explícitamente; el SDK utiliza la configuración de producción cuando env se omite.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
});

Abrir widget de pago#

Crea la orden en tu backend, devuelve su token al navegador y abre Payment Widget:

await DeunaSDK.initPaymentWidget({
  orderToken,
  language: 'en',
  callbacks: {
    onSuccess: async (order) => {
      await DeunaSDK.close();
      showConfirmation(order);
    },
    onError: (error) => showRetry(error),
    onClosed: (action, metadata) => {
      console.log('Widget closed', action, metadata);
    },
    onEventDispatch: (event, payload) => {
      analytics.track(event, payload);
    },
  },
});

Utiliza la llamada de retorno para actualizar la interfaz. Confirma y completa el pedido final a partir de un webhook verificado, en lugar de confiar únicamente en el estado del navegador.

Elige un modo de presentación#

El modal es el predeterminado. El SDK controla la superposición y close() la cierra.

Para un widget incrustado, utiliza tanto mode: 'target' como un selector CSS. Actualiza la altura del contenedor desde onResize para evitar que el contenido se recorte.

<div id="payment-widget"></div>

await DeunaSDK.initPaymentWidget({
  orderToken,
  mode: 'target',
  target: '#payment-widget',
  callbacks: {
    onResize: ({height}) => {
      document.querySelector('#payment-widget').style.height = `${height}px`;
    },
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
  },
});

Controla la presentación desde tu página.#

Oculta el botón de pago del widget cuando tu página es responsable de la llamada final a la acción. Valida antes de enviar y desactiva tu botón mientras se está procesando la solicitud.

await DeunaSDK.initPaymentWidget({
  orderToken,
  hidePayButton: true,
  callbacks,
});

payButton.addEventListener('click', async () => {
  if (!(await DeunaSDK.isValid())) return;

  payButton.disabled = true;
  const result = await DeunaSDK.submit();
  payButton.disabled = false;

  if (result.status === 'error') showRetry(result);
});

El widget activo también expone getWidgetState(), refetchOrder()y setCustomStyles(...). Llama setCustomStyles únicamente desde las llamadas de retorno del BIN de la tarjeta o de los plazos, según se documenta para el flujo de pago.

Experiencias disponibles#

Almacén de pagos y Pago con un clic

initElements abre el Pago Seguro de forma predeterminada. Proporciona types para seleccionar una experiencia diferente de Elements.

await DeunaSDK.initElements({
  orderToken,
  userInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    email: 'ada@example.com',
  },
  types: [{name: 'vault'}],
  callbacks: {
    onSuccess: (credential) => useSavedCredential(credential),
    onError: (error) => showRetry(error),
    onClosed: (action) => console.log(action),
  },
});

Uso {name: 'click_to_pay'} para Click to Pay. Si ya tienes un usuario de DEUNA autenticado, pasa userToken en lugar de userInfo.

Apple Pay y Google Pay

Cuando renderizas un botón de billetera de propiedad del comerciante, verifica la disponibilidad antes de mostrarlo. Realiza este paso antes del clic para que Apple Pay se abra directamente a partir de la acción del usuario.

const userInfo = {email: 'ada@example.com'};
const availableWallets = await DeunaSDK.getWalletsAvailable({
  orderToken,
  userInfo,
});

applePayButton.hidden = !availableWallets.includes('APPLE_PAY');

applePayButton.addEventListener('click', () => {
  DeunaSDK.initElements({
    orderToken,
    userInfo,
    types: [{name: 'APPLE_PAY'}],
    callbacks: {
      onSuccess: (credential) => useSavedCredential(credential),
      onError: (error) => showRetry(error),
      onClosed: () => showPaymentMethods(),
    },
  });
});

Uso GOOGLE_PAY para el flujo equivalente de Google Pay. Consulta las guías de Apple Pay y Google Pay para los requisitos del comerciante y del navegador.

Continúe con una acción pendiente

Abre la siguiente acción solo cuando la respuesta del pedido indique que se requiere una acción del cliente, como un desafío 3DS o una redirección.

await DeunaSDK.initNextAction({
  orderToken,
  callbacks: {
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

No crees un segundo pedido para este paso. Reutiliza el token para el pedido que requiere la siguiente acción.

Abrir un cupón

Utiliza la experiencia del cupón para los métodos de pago de efectivo o de cupón compatibles.

await DeunaSDK.initVoucherWidget({
  orderToken,
  callbacks: {
    onSuccess: (order) => showVoucherInstructions(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Carga un widget#

El Widget de Pago y Elements pueden crearse fuera de la pantalla durante la inicialización y mostrarse más tarde. Cargar reduce el tiempo percibido de carga, pero utiliza los recursos de la red y del navegador de forma más temprana.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
  preloadWidgets: [
    {
      widget: 'payment',
      params: {language: 'en'},
    },
  ],
});

// After the backend returns the order token:
await DeunaSDK.initPaymentWidget({orderToken});

Carga solo la experiencia que es probable que abra el cliente. La llamada posterior initPaymentWidget o initElements proporciona el token del pedido o del usuario y revela el widget preparado.

Datos de fraude del dispositivo#

El Widget de Pago inicia la recopilación de datos del dispositivo DEUNA cuando se abre. Si tu flujo necesita el identificador antes de que se abra un widget, llama generateFraudId(...) y envía el valor devuelto únicamente a través del pedido o del flujo de riesgo documentado.

const fraudId = await DeunaSDK.generateFraudId();

El comportamiento específico del proveedor y la versión están documentados en Integrar la huella digital del dispositivo.

Referencia del ciclo de vida y llamadas de retorno#

Guías y código relacionados#