Developer tools

Pago con referencia

Introducción

Pago con Referencia es una solución de DEUNA que unifica múltiples métodos de pago con referencia bajo una sola experiencia para el usuario final. En lugar de integrar individualmente soluciones como OXXO Pay, SafetyPay o BAZ, este método consolida todas en un flujo único, permitiendo al comprador elegir su canal favorito (tienda física, banca en línea, etc.) 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.

Requisitos

  • En la configuración del comercio se debe tener configurado previamente un método de pago de tipo reference.
    Consulta más de como configurar un método de pago alternativo aquí.
  • Revisar la guía de integración y uso del Payment Widget de DEUNA.

Paso 1: Crea una orden que acepte pagos 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 ...
  }
}

Paso 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: "YOUR_ORDER_TOKEN",
  callbacks: {...},
  ...
});










Paso 3: Visualización 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 SDK. Esta función requiere el token de la orden correspondiente al pago que se encuentra en estado processing.

Utiliza el callback onDownloadFile para escuchar cuando un comprobante debe ser descargado.


deunaSDK.initVoucherWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: {
    onDownloadFile: (file) => {
      const { type, data } = file;
      console.log("👀 onDownloadFile", type, data);
      const mapper = {
        [DownloadType.URL]: () => {
          // TODO: Implement download from url
        },
        [DownloadType.BASE64]: () => {
          // TODO: Implement download from image base64
        },
      };
      mapper[type]();
    },
  },
});














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.