Ganchos web

Los webhooks de DEUNA cubren dos flujos diferentes de servidor a servidor: notificaciones que publican cambios en el estado de pago a su backend, y devoluciones de llamada síncronas que permiten a DEUNA solicitar datos o lógica específicos del comerciante durante el checkout. Elija el flujo según lo que su integración necesite lograr.

Las redirecciones del navegador, las devoluciones de llamada del SDK y las devoluciones de llamada de proveedor a DEUNA son superficies de integración separadas. No las use como prueba de pago ni como reemplazo de estos flujos de backend.

Notificaciones del estado del pedido y del pagoPreguntar a Athia sobre esto#

Las notificaciones de estado entregan la instantánea más reciente del pedido a tu backend cuando el estado de pago normalizado coincide con un evento suscrito para el comerciante. Estas notificaciones son asíncronas: el ciclo de vida del pago no espera a que tu lógica de negocio termine.

Configurar entrega de estados

Defina el contrato de entrega para cada entorno:

Los eventos disponibles siguen el ciclo de vida de pago documentado en Flujo y estados de pago. La cobertura de eventos puede diferir por método de pago porque no todos los métodos admiten cada operación o estado de pago.

Payload predeterminado

Sin una transformación de carga útil personalizada, DEUNA envía un HTTP POST con Content-Type: application/json y el pedido actual bajo la propiedad order :

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

El pedido puede contener los datos de cliente, artículo, monto, pago, procesador, fraude, metadatos y campo personalizado asociados con esa transacción. Trate order.payment.data.status como el estado de pago autoritativo, y use order.token, order.order_idy los identificadores de transacción aplicables para la conciliación.

Una configuración específica del comerciante puede cambiar el método HTTP, los encabezados, los parámetros de URL, los estados suscritos y la forma de la carga útil. Si una configuración personalizada está habilitada, implemente el contrato exacto certificado para ese comerciante en lugar de asumir el cuerpo predeterminado.

Verifique la firma

La entrega actual agrega un X-Signature encabezado. Esto reemplaza ejemplos anteriores que se refieren a X-Deuna-Signature.

1. Lea el cuerpo de la solicitud sin modificar antes de que un framework lo analice o reserialice.
2. Aplique el procedimiento de verificación HMAC-SHA256 y Base64 certificado para el flujo y entorno de entrega.
3. Compare el valor calculado con X-Signature usando una comparación de tiempo constante.
4. Rechace la solicitud antes de procesarla si los valores no coinciden.

Las notificaciones de estado y los webhooks dinámicos no siempre firman la misma entrada cuando la transformación de carga útil está habilitada. No reutilice un verificador entre esos flujos hasta que la entrada firmada y la derivación de claves hayan sido confirmadas durante la certificación.

Mantenga las claves de API privadas en el servidor. Nunca las coloque en código del navegador, aplicaciones móviles, registros o respuestas de webhooks.

Reconozca y concilie

1. Verifique la firma antes de confiar en la carga útil.
2. Registre una clave de deduplicación que incluya el token del pedido y el evento o estado de pago resultante.
3. Devuelva una respuesta exitosa de 2xx tan pronto como la solicitud sea aceptada de manera duradera.
4. Vuelva a leer o concilie el estado autoritativo del pedido antes de un cumplimiento, cancelación, captura, reembolso u otra acción irreversible.
5. Ignore una notificación que movería su registro local hacia atrás desde un estado más reciente.

Los fallos de entrega pueden reintentarse. No asuma entrega exactamente una vez, un intervalo de reintento fijo o llegada en orden del ciclo de vida.

Webhooks de pago dinámicoPreguntar a Athia sobre esto#

Los webhooks dinámicos son devoluciones de llamada síncronas específicas del comerciante. Cuando el checkout activa un evento configurado, DEUNA envía una solicitud firmada a su endpoint, valida la respuesta, aplica solo las actualizaciones permitidas y devuelve el resultado configurado al checkout.

Los webhooks dinámicos se habilitan y configuran como parte de la implementación del comerciante. No se registran desde código del navegador o móvil.

Flujo de configuración y ejecución

Configure el webhook con DEUNA como parte de la configuración de su comercio. Acuerde el nombre del evento, destino, formatos de solicitud y respuesta, reglas de validación y campos que la devolución de llamada puede actualizar. Después de la configuración, el checkout puede ejecutar el evento a través del mismo contrato acordado.

Si el evento no está configurado para el comerciante y el entorno, DEUNA no llama a su endpoint. Trate una devolución de llamada requerida que no se ejecutó como un problema de configuración durante la certificación.

Capacidades de configuración

El siguiente extracto muestra el núcleo de una definición de cálculo de propina. Son datos de configuración, no una solicitud que deba enviarse desde el navegador:

{
  "event_name": "tip_amount_updated",
  "url": "https://merchant.example.com/checkout/tips",
  "http_method": "POST",
  "fields_update": {
    "fields": ["TotalAmount"],
    "custom_fields": ["tipAmount"]
  },
  "response_body": {
    "fields": ["Order"],
    "custom_fields": ["tipAmount"]
  },
  "response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
  "response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}

Durante la ejecución, el checkout puede proporcionar entrada específica del evento:

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

Sin una plantilla de carga útil, el endpoint del comerciante recibe esos datos del evento. Con una plantilla de carga útil, la plantilla puede usar tanto el pedido actual como la entrada del evento para construir el JSON saliente.

Implementar el endpoint del comerciante

Las llamadas dinámicas incluyen X-Signature y X-Deuna-Operation. Cuando una plantilla de carga útil cambia el cuerpo saliente, usar la entrada de verificación de firma acordada durante la certificación; no asumir que es idéntica al contrato de notificación de estado anterior.

Si la propagación de respuesta está deshabilitada, la respuesta predeterminada del comerciante puede contener order, shipping_ratey shipping_methods; DEUNA devuelve solo los campos de respuesta seleccionados por la configuración. Si la propagación de respuesta está habilitada, la respuesta del comerciante debe ser JSON válido y se devuelve directamente como el resultado dinámico.

Patrones prácticos

Ejemplo de cálculo de propina

Este ejemplo muestra la ruta completa de checkout a comerciante para un evento de propina configurado.

Para una definición de propina, poner en la lista blanca solo el monto y los campos personalizados que se espera que cambie la respuesta del comerciante. El endpoint del comerciante sigue siendo responsable de calcular un total de pedido consistente.

Pruebe en el entorno de pruebaPreguntar a Athia sobre esto#

Probar notificaciones de estado

Probar un webhook dinámico

Documentación relacionadaPreguntar a Athia sobre esto#