Ganchos web

DEUNA utiliza webhooks para enviar a tu backend una instantánea actualizada del pedido cuando cambia el estado de pago o del pedido, según esté configurado. El cuerpo predeterminado para el usuario comercial contiene la información del pedido. No es un envoltorio de evento similar a Stripe.

Cómo funciona#

Configure el destino#

Para Purchase V2, proporciona la URL de recepción HTTPS en el campo de notificación de pedido asíncrono mostrado a continuación:

{
  "order": {
    "order_id": "merchant-order-123",
    "webhook_urls": {
      "notify_order": "https://merchant.example.com/webhooks/deuna/orders"
    }
  }
}

DEUNA almacena una URL a nivel del pedido y puede completar un valor faltante a partir de la configuración del comercio establecida durante el onboarding. El flujo actual de notificaciones firmadas utiliza el destino y la suscripción de estados a nivel del comercio; confirme con su TAM la URL efectiva para cada entorno. Los campos de URL de webhook asíncrono y síncrono son mutuamente excluyentes para un pedido.

Las notificaciones de estado del pedido no utilizan un recurso genérico de registro de endpoints de webhook. Configure el campo del pedido anterior o utilice la configuración a nivel del comercio acordada con su Technical Account Manager (TAM) de DEUNA. Las devoluciones de llamada dinámicas del checkout utilizan la API independiente descrita a continuación.

Flujos de entrega compatibles#

Utilice la entrega asíncrona a menos que DEUNA haya habilitado y certificado explícitamente otro modo para su integración.

DEUNA crea candidatos de notificación cuando cambian los valores admitidos del estado del pedido o del pago, cuando cambia el procesador seleccionado y para decisiones admitidas de fraude o 3DS. La suscripción configurada determina qué estados de pago se entregan. No todas las transiciones de estado generan un webhook.

Este mecanismo cubre las actualizaciones de compra y los resultados finales de las operaciones asíncronas de captura, reembolso y anulación soportadas. Consulte Flujo y estados de pago para los estados públicos y Captura, reembolso y anulación asíncronas para los flujos de estas operaciones.

Webhooks de pago dinámico#

Los webhooks dinámicos del checkout son un flujo síncrono independiente. Permiten que una acción del checkout llame a un endpoint del comercio por nombre de evento, valide o transforme la respuesta, actualice campos seleccionados en el pedido tokenizado y devuelva valores seleccionados o la respuesta del comercio al solicitante.

Utilice este flujo para acciones de pago específicas del comerciante, como propinas, puntos de fidelidad, donaciones y comportamiento de cupones personalizados. No lo utilice como reemplazo para la entrega asíncrona del estado de pago.

La API Gateway activa expone estas operaciones de webhooks dinámicos:

La solicitud de ejecución puede pasar entradas específicas del evento en data:

{
  "data": {
    "tip_amount": 500
  }
}

DEUNA carga la configuración activa para el comercio y el nombre del evento y, a continuación, llama a la URL configurada del comercio. La configuración puede seleccionar el método HTTP, los encabezados, los parámetros de URL y de consulta, las plantillas de payload y respuesta, las validaciones, los campos del pedido que se actualizarán, los campos de respuesta que se devolverán y si se propagará la respuesta del comercio.

La solicitud del comerciante de salida incluye X-Signature y X-Deuna-Operation. La ejecución es síncrona: los tiempos de espera del comercio, las respuestas no válidas, las validaciones fallidas y las respuestas HTTP no satisfactorias se devuelven al solicitante. Si el comercio no tiene una configuración para el nombre del evento, DEUNA devuelve una respuesta satisfactoria vacía sin llamar a un endpoint del comercio.

La configuración del webhook dinámico es específica del comercio y puede modificar un pedido. Confirme con su TAM el nombre del evento, la autenticación, los campos permitidos, las plantillas, las validaciones, el tiempo de espera y la respuesta propagada antes de habilitarla. Consulte catálogo de endpoints para el inventario de la gateway.

Carga predeterminada del estado del pedido#

La solicitud predeterminada es una solicitud HTTP POST con Content-Type: application/json con la siguiente estructura:

{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "refunded",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "refunded",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

El objeto de pedido completo puede contener los mismos campos de pedido, cliente, artículo, importe, pago, procesador, fraude y metadatos que se devuelven en una respuesta de pedido.

• Estado de pago autorizado: order.payment.data.status
• Identificadores comerciales estables: order.token, order.order_id, y los identificadores de transacción aplicables

Las configuraciones personalizadas del comerciante pueden transformar este cuerpo. Si tu receptor no utiliza la forma predeterminada mostrada anteriormente, confirma el esquema exacto con tu gestor técnico de DEUNA (TAM).

Autenticar la entrega del estado del pedido#

El flujo de entrega actual envía este encabezado de solicitud:

X-Signature: <signature>

La firma se deriva mediante HMAC-SHA256 y codificación Base64 del esquema JSON y las credenciales del comerciante.

Valida el esquema de solicitud exacto con las credenciales y el procedimiento de verificación proporcionados durante la incorporación antes de confiar en el esquema. No confíes en nombres de encabezado alternativos ni en ayudantes SDK no documentados.

Reconocer y procesar#

Devuelve el estado HTTP 200 o cualquier otra respuesta 2xx tan pronto como la solicitud se haya validado y se haya encolado de forma duradera. Puedes devolver un cuerpo vacío. Si devuelve JSON, DEUNA acepta esta forma de respuesta:

{
  "status": "success",
  "data": {
    "order_id": "merchant-order-123"
  }
}

Solo devuelve un identificador de pedido diferente y no vacío en esta respuesta cuando pretendes que DEUNA reemplace el identificador de pedido del comerciante.

Errores de red, tiempos de espera y respuestas de error pueden provocar un nuevo intento de entrega. No dependa de un intervalo de reintento fijo, y no asuma el orden de entrega. Haga que el procesamiento sea idempotente y reconcilie cada instantánea con el estado de pago más reciente conocido.

Pruebe en el entorno de prueba#

1. Expona un receptor HTTPS que registre los encabezados de la solicitud y el cuerpo sin modificar.
2. Establece la URL de notificación de pedido asíncrona en una solicitud de prueba de Purchase V2, a menos que ya esté configurada una URL a nivel de comerciante.
3. Complete un pago o una captura, reembolso o anulación asíncrona que cambie el estado del pago.
4. Confirma la forma del esquema, la cobertura de estado configurada, el comportamiento del encabezado firmado, la confirmación y el manejo de duplicados.

El flujo de estado del pedido no proporciona la API genérica /webhook_endpoints ni un comando CLI local. Pruebe el flujo produciendo cambios reales en el entorno de sandbox. Pruebe los webhooks de pago dinámico a través de sus rutas de configuración y ejecución verificadas.