Pago con Referencia es una solución que unifica múltiples métodos de pago con referencia bajo una sola experiencia para el usuario final.

Este método consolida todas en un flujo único, permitiendo al comprador elegir su canal favorito desde un solo widget.

Esta integración está especialmente diseñada para comercios que desean ofrecer pagos diferidos (offline) sin la complejidad de múltiples integraciones técnicas.

Requerimientos

Para usar pagos con referencia necesitas:

Una Conexión activa de tipo reference.
El Payment Widget ya inicializado.

1. Crea una orden de pago con referencia

Usando la API de DEUNA crea una nueva orden.

En el cuerpo (body) de la petición de creación de la orden, dentro del objeto order, debes incluir el atributo include_payment_options.

El atributo include_payment_options espera una lista de objetos. Cada objeto en esta lista define un método de pago específico que deseas habilitar para esta orden. Para ofrecer pagos con referencia, incluye un objeto con las siguientes propiedades:

payment_method: Establece el valor a "reference". Esto indica que deseas ofrecer la opción de pago con referencia.
processors: Define una lista de los procesadores de pago con referencia que deseas habilitar para esta orden en particular. Ejemplos: "baz_reference", "oxxo_reference", "safetypay_express", etc.

Para obtener detalles completos sobre la estructura de la petición para crear una orden, consulta la documentación de la API de creación de órdenes aquí.

Ejemplo de Cuerpo de Petición (Request Body) en formato JSON:

{
  "order": {
     // ... otros atributos de la orden (por ejemplo, `amount`, `currency`) ...
    "include_payment_options": [
      {
        "payment_method": "reference",
        "processors": [
          "baz_reference",
          "oxxo_reference",
          "safetypay_express"
        ]
      }
    ]
	// ... otros atributos de la orden ...
  }
}

2. Muestra el Payment Widget

Una vez que has creado exitosamente la orden y has recibido el token de la orden en la respuesta, el siguiente paso es integrar y mostrar el Payment Widget de DEUNA en tu página web. Esto se realiza utilizando la función DeunaSDK.initPaymentWidget(...) proporcionada por nuestro Web SDK.

deunaSDK.initPaymentWidget(
  orderToken: "<DEUNA order token>",
  callbacks: PaymentWidgetCallbacks(
    onSuccess: { order in
      self.deunaSDK.close()
    },
    onError: { type in
      // Manejo de errores
    },
    onClosed: { action in
      // Widget cerrado
    },
  ),
)

3. Visualiza y descarga del comprobante de pago

Una vez que el usuario interactúa con el Payment Widget, ya sea presionando el botón de pagar o cuando se invoca la función submit para enviar la solicitud de pago, el estado de la orden en el sistema de DEUNA cambiará a pending, y el estado del pago asociado se actualizará a processing.

Para permitir al usuario visualizar y descargar el comprobante de pago generado para su transacción con referencia, debes utilizar la función deunaSDK.initVoucherWidget proporcionada por nuestro Web SDK. Esta función requiere el token de la orden correspondiente al pago que se encuentra en estado processing.

deunaSDK.initVoucherWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: PaymentWidgetCallbacks(...)
  ...
});

Otras Consideraciones Importantes

Esta sección destaca algunos puntos clave a tener en cuenta al trabajar con pagos con referencia y la visualización de comprobantes:

Verificación de Condiciones para el Comprobante: Si el comprobante de pago no se muestra, es fundamental verificar que la orden y el pago cumplan con las condiciones establecidas en el Paso 3. Asegúrate de que el estado de la orden sea pending y el estado del pago sea processing. Cualquier otro estado podría significar que el comprobante aún no se ha generado o no está disponible.
Variabilidad de la Información del Comprobante: La estructura y la información contenida en el comprobante de pago pueden variar significativamente dependiendo del procesador de referencia específico que el cliente haya seleccionado (por ejemplo, Baz, Oxxo, SafetyPay). Algunos procesadores pueden incluir códigos de barras, números de referencia específicos, instrucciones de pago detalladas o fechas de vencimiento, mientras que otros pueden presentar la información de manera diferente. Es importante tener en cuenta esta variabilidad al brindar soporte a tus usuarios.
Manejo de Múltiples Comprobantes (si aplica): En ciertos escenarios, podría haber más de un comprobante asociado a una orden de pago con referencia. Si esto ocurre, la interfaz del VoucherWidget debería permitir al usuario seleccionar y visualizar o descargar el comprobante que necesite. Asegúrate de que tu integración maneje correctamente esta posibilidad y ofrezca una experiencia clara al usuario.
Alternativas en Caso de No Disponibilidad del Comprobante: Si, por alguna razón, los comprobantes de pago no están disponibles (por ejemplo, un error en el procesamiento del pago o una situación inusual con el procesador), tu aplicación debería estar preparada para ofrecer alternativas al usuario. Esto podría incluir mostrar un mensaje informativo, ofrecer la posibilidad de reintentar el pago, o proporcionar otros métodos de contacto o soporte para resolver la situación. Una buena gestión de estos casos puede mejorar significativamente la experiencia del usuario.