Payment Widget - Android

Con el Payment Widget de DEUNA, acepta pagos de forma ágil y rápida en tu app Android. Sigue los siguientes pasos para capturar un pago utilizando el Payment Widget.

Paso 1: Completar los Primeros Pasos

Antes de integrar el Payment Widget, es necesario que completes la sección de primeros pasos. En esta sección, te explicamos los requisitos necesarios y cómo inicializar el SDK. Puedes encontrar más información en Primeros Pasos con el SDK de iOS.

Una vez que hayas completado estos pasos, podrás continuar con el paso 2.

Paso 2: Mostrar el Widget

Para mostrar el Payment Widget, llama a la función initPaymentWidget pasando los siguientes datos:

let deunaSDK: DeunaSDK = ....

deunaSDK.initPaymentWidget(
  context = YOUR_ACTIVITY_CONTEXT,
  orderToken = "<DEUNA order token>",
  userToken = "<DEUNA user token>", // optional
  callbacks = PaymentWidgetCallbacks().apply {
    onSuccess = { data ->
      deunaSDK.closePaymentWidget(...) // Cierra el widget de pago
      // Tu código adicional
    }
    onCardBinDetected = { metadata, refetchOrder ->
      if (metadata != null) {
        // Tu código aquí
      }
    }
    onInstallmentSelected = { metadata, refetchOrder ->
      // Tu código aquí
    }
    onCanceled = {
      // El widget de pago fue cerrado por el usuario
      // No es necesario llamar a closePaymentWidget(...)
    }
    onError = { type ->
      // Manejo de errores
    }
    onClosed = {
      // Widget cerrado
    }
  }
)

Parámetros

AtributosDescripción
contextEl context es el contexto de tu Activity en Android. Proporciona acceso a recursos específicos de la aplicación y a la información del entorno en el que se está ejecutando la aplicación.
orderTokenEl orderToken es un token único generado para la orden de pago. Este token es generado a través del API de DEUNA y debes implementar el endpoint correspondiente en tu backend para obtener esta información.
callbacksLos callbacks son funciones de retorno que se encargan de escuchar y manejar los eventos del widget de pago. Estos eventos permiten gestionar acciones específicas basadas en el estado del pago. Los principales callbacks incluyen: onSuccess, onError, onClosed, onCanceled, onCardBinDetected, onInstallmentSelected
userToken(Opcional)El bearer token del usuario de DEUNA. Cuando este es enviado, todas las acciones dentro del widget van a hacer sobre este usuario de DEUNA.

Importante: para que este userToken sea usado y se le muestren las tarjetas guardadas al cliente, el correo asociado a ese userToken debe ser el mismo que se envía al crear la orden en billing_address.email. En caso que ambos correos no coincidan, se usará el flujo sin mostrar las tarjetas por seguridad.


Paso 3: Escuchar los Eventos del Widget de Pago

Cuando una transacción es exitosa o falla, es importante actualizar tu interfaz para notificar a los usuarios sobre el resultado de la transacción. Esto lo puedes realizar escuchando los eventos del widget de pago mediante los callbacks.

La instancia de la clase PaymentWidgetCallbacks pasada a la función initPaymentWidget te permite escuchar los eventos del widget mediante callbacks. Define los callbacks respectivos para actualizar la interfaz de tu app.

3.1. Callbacks

Callback¿Cuándo se dispara?
onSuccessSe ejecuta cuando se completó el pago. Este callback contiene un parámetro de tipo CheckoutResponseData con la información de la orden.
onCanceledSe ejecuta cuando el usuario de forma intencional cierra el widget de pago (presionando el botón X o presionando el botón de retroceso) sin que la operación se haya completado.
onErrorSe ejecuta cuando ocurre un error al procesar el pago. Este callback contiene un parámetro tipo enum PaymentWidgetsErrorType el cual identifica el tipo de error producido al momento de procesar el pago.
onClosed (Opcional)Se ejecuta cuando se cierra el widget de pago, independientemente si el pago se realizó con éxito, ocurrió un error o el usuario canceló la operación.

NOTA: El orden de ejecución de onCanceled y onClosed es el siguiente:

- Si el usuario cierra manualmente el widget (presionando el botón X o presionando el botón de retroceso):
onCanceled > onClosed.

- Si se cierra el widget mediante código llamando a closePaymentWidget, solo se ejecuta onClosed.
onCardBinDetected (Opcional)Se ejecuta cuando el widget de pago detecta el BIN de una tarjeta de crédito o débito ingresada o cuando el usuario borra el número de la tarjeta ingresada.

Este callback contiene un parámetro de tipo CardBinMetadata con la información del bin y la marca de la tarjeta ingresada.
NOTA: El parámetro de tipo CardBinMetadata será nulo cuando el usuario elimina el texto ingresado en el campo del número de tarjeta.
onInstallmentSelected (Opcional)Si la orden se puede diferir, este callback se ejecutará cuando el usuario seleccione los meses a diferir.

Este callback contiene un parámetro de tipo InstallmentMetadata con la información de los meses a diferir seleccionados por el usuario.

NOTA: El parámetro de tipo InstallmentMetadata será nulo cuando el usuario selecciona pago corriente (Sin cuotas).

Paso 4 (Opcional): Cerrar el Widget

Por defecto, el widget de pago solo se cierra cuando el usuario presiona el botón de cerrar del widget o cuando presiona el botón de "retroceso" en Android. Para cerrar el modal cuando un pago es exitoso o cuando ocurre un error, debes llamar a la función closePaymentWidget.

El siguiente código de ejemplo muestra cómo cerrar el widget cuando un pago es exitoso.

deunaSDK.initPaymentWidget(
  context = YOUR_ACTIVITY_CONTEXT,
  orderToken = "<DEUNA order token>",
  userToken = "<DEUNA user token>", // optional
  callbacks = PaymentWidgetCallbacks().apply {
    onSuccess = { data -> 
      deunaSDK.closePaymentWidget(...) // Cierra el widget de pago
      // Tu código adicional
    }
  }
)

Paso 5 (Opcional): Revisar Ejemplo Demo App

Para comprender mejor la integración del Vault Widget, revisa el proyecto de ejemplo proporcionado por DEUNA. Este ejemplo te ayudará a entender mejor cómo implementar el widget en tu aplicación Android.

Para acceder al proyecto de ejemplo y obtener más información, consulta la documentación del Ejemplo de Proyecto para Android.