Saltar al contenido principal
En esta página

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.

FlujoCuándo se ejecutaÚselo para
Notificación del estado del pedido y del pagoDespués de que cambia un estado de pago suscritoActualice el estado de cumplimiento, conciliación y pedido del cliente sin hacer sondeos continuos.
Webhook dinámico de checkoutMientras el checkout espera una respuesta del comercianteAplica cupones o descuentos por tarjeta, calcula propinas o impuestos, consulta información de envío o valida datos.

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 pago#

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.

01 · state
Cambios de estado de pago
DEUNA registra un resultado de pago normalizado como procesado, autorizado, capturado, denegado, anulado o reembolsado.
02 · subscription
Se selecciona el evento
El estado del pago se convierte en un evento llamado Estado de pagoy DEUNA verifica la suscripción del comercio.
03 · delivery
Se envía la instantánea del pedido
DEUNA envía la solicitud configurada al destino del comercio.
04 · receiver
Tu backend concilia
Tu servidor verifica la firma, confirma la solicitud y procesa la actualización de forma idempotente.

Configurar entrega de estados

Defina el contrato de entrega para cada entorno:

ConfiguraciónQué definir
DestinoEl endpoint HTTPS que acepta notificaciones de estado.
EventosEl payment.<status> eventos requeridos por su ciclo de vida de pedido.
Contrato de solicitudCualquier encabezado estático, parámetro de URL y transformación de carga útil aprobada.
Manejo de fallosEl comportamiento de acuse de recibo, reintento, monitoreo y conciliación acordado para la integración.

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 :

Notificación de estado de pedidoJSON
{
  "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ámico#

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.

Diagrama de secuencia
1Merchant team andbackend2DEUNA3Checkout UIConfigure event, endpoint,contract, and allowedupdatesTrigger the configured eventwith order and inputSend the signed requestReturn the agreed JSONresponseValidate the responseand apply permittedupdatesContinue with the configuredresult
Comercio o clienteDEUNA

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

ConfiguraciónRequisitoQué controla
event_nameRequeridoNombre de evento específico del comercio que usa letras, números, guiones o guiones bajos. Configura su activador por separado.
urlRequeridoDestino del endpoint del comercio. Usa HTTPS para la integración.
http_methodOpcionalMétodo HTTP: GET, POST, PUT, o PATCH. El valor predeterminado es POST.
headersOpcionalArray de pares de key y value para encabezados adicionales de la solicitud. Los valores pueden usar plantillas del pedido.
params, query_paramsOpcionalArrays de pares de key y value para marcadores de posición de la URL y parámetros de consulta. Los valores pueden usar plantillas del pedido.
payload_templateOpcionalConstruye la solicitud JSON al comercio a partir del pedido actual y los datos del evento. Sin esta plantilla, el cuerpo de la solicitud contiene solo los datos del evento.
response_templateOpcionalMapea el JSON del comercio al contrato de respuesta del pedido. Omítela si tu endpoint ya devuelve ese contrato.
response_dataObligatorio con response_templateJSON codificado como cadena, usado para validar la plantilla de respuesta durante la configuración. No es la respuesta del comercio durante la ejecución.
error_response_templateOpcionalMapea un formato alternativo de error del comercio. Sin esta plantilla, las respuestas de error del comercio usan code y message.
fields_update.fieldsOpcionalArray de actualizaciones del pedido permitidas. Incluye cada importe, lista de descuentos o campo de artículo que el callback deba reemplazar. Consulta los campos de precios a continuación.
fields_update.custom_fieldsOpcionalArray de nombres de campos personalizados que pueden cambiar. Los campos deben estar declarados y los valores devueltos deben cumplir el esquema de campos personalizados del pedido.
response_body.fieldsObligatorio al crear la configuraciónAcepta Order, ShippingRate, y ShippingMethods. La respuesta mapeada incluye el pedido; esta lista también selecciona resultados adicionales de envío. No restringe las propiedades que aparecen dentro del pedido.
response_body.custom_fieldsOpcionalArray de nombres de campos personalizados declarados que se incluyen en el resultado del checkout. Es independiente del permiso para actualizar esos campos.
propagate_responseOpcionalEl valor predeterminado es false. Mantenlo en false para actualizar pedidos; la alternativa incluye el JSON del comercio en dynamic_response en lugar del resultado del pedido mapeado.

Configura las actualizaciones de precios

Los nombres de los campos de configuración y las rutas JSON de la respuesta son distintos. Selecciona solo las actualizaciones que necesita tu promoción:

Valor en fields_update.fieldsDatos de la respuesta del comercioComportamiento de actualización
TotalAmountorder.total_amountReemplaza el total a pagar.
TotalDiscountorder.total_discountReemplaza el importe total de descuento.
Discountsorder.discountsReemplaza todo el array de descuentos del pedido.
Items.TotalAmountorder.items[].id, order.items[].total_amountBusca los artículos existentes por ID y actualiza su importe, importe original y descuento total.
Items.Discountsorder.items[].id, order.items[].discountsBusca los artículos existentes por ID y reemplaza sus referencias de descuentos.
Shippingorder.shippingReemplaza el importe original del envío, su descuento total y las referencias de descuentos.

El webhook asigna estos valores de forma independiente. No recalcula el total a pagar, los descuentos acumulados ni la distribución por artículo a partir de la lista de descuentos. Devuelve todos los campos permitidos en cada llamada exitosa. Omitir un campo seleccionado puede restablecer un importe a cero o vaciar una lista; no es una instrucción de actualización parcial.

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:

Extracto de configuración de webhook dinámicoJSON
{
  "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:

Entrada del eventoJSON
{
  "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

PreocupaciónRequisito del endpoint del comerciante
Ejecución repetidaProcesa de forma idempotente los datos repetidos. Recalcula cuando cambien los datos de la promoción.
Contrato de respuestaDevolver JSON que coincida con la forma de respuesta configurada o la plantilla de respuesta.
Campos obligatoriosIncluye todos los campos de actualización configurados, incluidos los valores cero al eliminar un descuento.
LatenciaCompletar dentro del tiempo de espera certificado para la integración porque el checkout espera la respuesta.
ErroresDevolver una respuesta no-2xx para un fallo comercial o de procesamiento, usando la forma de error configurada.

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.

Con la propagación de respuestas desactivada, la respuesta del comercio puede contener order, shipping_rate, y shipping_methods. DEUNA devuelve el pedido mapeado y los resultados adicionales configurados. Con la propagación activada, la respuesta del comercio debe ser JSON válido y se expone en dynamic_response. Usa el flujo mapeado para recalcular el precio del pedido.

Patrones prácticos

Descuentos por tarjeta

Usa un webhook dinámico de checkout para aplicar una promoción según la tarjeta introducida durante el checkout. Tu backend determina la elegibilidad y calcula el descuento; DEUNA aplica las actualizaciones del pedido configuradas antes del pago.

Tu backend gestiona los números de identificación bancaria (BIN), las marcas de tarjeta y las reglas de descuento elegibles. Tu DEUNA Technical Account Manager (TAM) no necesita esa lista de elegibilidad. DEUNA llama al endpoint cuando se ejecuta el activador configurado; tu endpoint evalúa cada solicitud y devuelve el pedido con descuento o el pedido sin esa promoción.

Un callback configurado antes del pago se ejecuta antes de cada solicitud de pago que pasa por ese flujo configurado, sin que DEUNA filtre la elegibilidad por BIN. Un callback de detección de BIN puede ejecutarse antes para actualizar el precio del checkout cuando el cliente introduce o cambia la tarjeta. Confirma con DEUNA cuándo se ejecuta el callback y qué datos recibe.

Completa el recálculo del precio y actualiza el pedido antes de que el checkout construya la solicitud de pago. Actualizar los totales guardados del pedido dentro de un callback previo al pago no reconstruye automáticamente los importes ya incluidos en esa solicitud de pago.

El siguiente ejemplo usa la detección de BIN. La introducción de la tarjeta puede generar un evento de BIN tras los seis primeros dígitos, antes de que el cliente complete los datos de la tarjeta. Detectar el BIN no confirma que la tarjeta completa sea válida ni que se haya autorizado un pago.

Diagrama de secuencia
1Checkout2DEUNA3Backend delcomercioBIN de tarjeta detectado omodificadoEjecuta el evento dedescuento configuradoSolicitud firmada con pedidoy datos de tarjetaEvalúa la elegibilidad ycalcula los totalesTarjeta elegibleTotales rebajados y lista dedescuentosTarjeta no elegibleTotales y descuentos sinesta promociónGuarda las actualizacionespermitidas del pedidoPedido y totalesactualizadosMuestra el precio y construyela solicitud de pagoEnvía el pago con el totalactualizado
Comercio o clienteDEUNA

Configura e implementa este flujo en cada entorno:

  1. Configura el webhook con DEUNA. Facilita a tu DEUNA Technical Account Manager (TAM) el destino HTTPS y la solicitud y respuesta esperadas. Acuerda el nombre del evento, cuándo se ejecuta el callback, la verificación de firma, el tiempo de espera, el tratamiento de errores y los campos del pedido que la respuesta puede actualizar. Mantén la elegibilidad de la promoción y el cálculo del descuento en tu backend.
  2. Conecta el activador acordado. Para un callback previo al pago, configura su ejecución con DEUNA para el flujo de pago necesario. Para el ejemplo de detección de BIN que aparece a continuación, coordina la conexión del checkout para que un BIN detectado o modificado ejecute el evento acordado. Registrar un webhook por sí solo no lo conecta con la introducción de la tarjeta. En Payment Widget y Elements del Web SDK, onCardBinDetected expone cardBin y cardBrand; consulta la referencia de callbacks del Web SDK. El callback del cliente y el webhook entre servidores son pasos separados.
  3. Implementa el endpoint del comercio. Verifica la solicitud firmada y evalúa la promoción en tu servidor con los datos del pedido y el BIN acordados. Mantén las credenciales privadas en el servidor y no solicites el número completo de tarjeta ni el código de seguridad para este flujo. Gestiona las llamadas repetidas sin acumular el mismo descuento.
  4. Devuelve el pedido recalculado. Devuelve el total a pagar revisado, el descuento acumulado y el array completo de descuentos en la respuesta JSON acordada. Configura las tres actualizaciones permitidas que se muestran a continuación y devuelve el pedido mapeado al checkout. Acuerda una plantilla de respuesta si tu endpoint usa otro formato y desactiva la propagación de respuestas para esta actualización.
  5. Actualiza el precio antes del pago. Muestra el pedido devuelto por DEUNA y usa su total revisado para el pago. Acuerda cómo el checkout elimina o recalcula la promoción cuando el cliente cambia o borra la tarjeta. Define si el checkout reintenta, bloquea el pago o continúa sin la promoción cuando falla el callback.

Por ejemplo, una promoción del 10% en un pedido de USD 100.00 sin otros cargos genera un descuento de USD 10.00 y un total a pagar de USD 90.00. Tu endpoint debe calcular totales coherentes; devolver solo un indicador de elegibilidad no cambia el importe del pedido.

Ejemplo de contrato de solicitud y respuesta

El siguiente ejemplo corresponde a un pedido sin otros descuentos ni cargos. El nombre del evento y la estructura de la solicitud saliente son un ejemplo de acuerdo con el comercio, no un evento de descuento por tarjeta integrado ni un esquema predeterminado para todos los comercios. Confirma el contrato y la conexión del checkout con tu TAM antes de usarlo.

Los importes son enteros expresados en las unidades menores de la moneda del pedido: 10000 representa USD 100.00. Mantén el BIN como cadena para conservar los ceros iniciales.

El checkout proporciona estos datos al ejecutar el evento acordado:

Datos de checkout para el evento de ejemplo card_discountJSON
{
  "data": {
    "cardBin": "411111",
    "cardBrand": "visa"
  }
}

Configura el siguiente mapeo con DEUNA. Es un fragmento de configuración, no una solicitud del navegador. La plantilla del payload combina el pedido actual con los datos del evento; sin ella, el comercio recibe únicamente los datos del evento.

Ejemplo de configuración del webhook de descuento por tarjetaJSON
{
  "event_name": "card_discount",
  "url": "https://merchant.example.com/checkout/card-discounts",
  "http_method": "POST",
  "payload_template": "{\"order_token\":\"{{ .Order.Token }}\",\"order_id\":\"{{ .Order.OrderID }}\",\"currency\":\"{{ .Order.Currency }}\",\"total_amount\":{{ .Order.TotalAmount }},\"cardBin\":\"{{ .Payload.cardBin }}\",\"cardBrand\":\"{{ .Payload.cardBrand }}\"}",
  "fields_update": {
    "fields": ["TotalAmount", "TotalDiscount", "Discounts"]
  },
  "response_body": {
    "fields": ["Order"]
  },
  "propagate_response": false
}

El endpoint del comercio recibe una solicitud equivalente al siguiente cURL. DEUNA proporciona los valores de los encabezados de firma y operación. Confirma la verificación de firma para payloads transformados con tu TAM.

curl --request POST 'https://merchant.example.com/checkout/card-discounts' \
  --header 'Content-Type: application/json' \
  --header 'X-Signature: SIGNATURE_FROM_DEUNA' \
  --header 'X-Deuna-Operation: OPERATION_FROM_DEUNA' \
  --data '{
    "order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "currency": "USD",
    "total_amount": 10000,
    "cardBin": "411111",
    "cardBrand": "visa"
  }'

Los campos del pedido identifican el pedido cuyo precio se recalcula; los campos de tarjeta contienen los datos del evento. Valida los datos en tu servidor y usa tus reglas autorizadas de precios y promociones. Recalcula a partir del importe base de la promoción de tu pedido, porque el total recibido puede incluir un descuento de una llamada anterior. Acuerda cómo gestionar una marca desconocida o un BIN vacío cuando se borra la tarjeta.

Para una tarjeta elegible, devuelve la siguiente respuesta con un estado HTTP de éxito y un cuerpo JSON:

Respuesta del comercio: tarjeta elegibleHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 9000,
    "total_discount": 1000,
    "discounts": [
      {
        "amount": 1000,
        "code": "CARD_PROMO",
        "reference": "merchant-promotion-123",
        "description": "Card promotion",
        "type": "order_value",
        "discount_category": "promotion"
      }
    ]
  }
}
Campo de respuestaTipo JSONObligatorio en este ejemploSignificado
order.total_amountintegerSíTotal final a pagar en unidades menores de la moneda, después del descuento.
order.total_discountintegerSíDescuento total en las mismas unidades, incluida la promoción por tarjeta.
order.discountsarray de objetosSíLista completa de descuentos que se guardará en el pedido. Un array vacío borra esta lista.

Devuelve los tres campos configurados en cada llamada exitosa, incluidas las que eliminan la promoción. Para una tarjeta no elegible en este ejemplo, devuelve:

Respuesta del comercio: sin descuento por tarjetaHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 10000,
    "total_discount": 0,
    "discounts": []
  }
}

DEUNA actualiza únicamente los campos permitidos por fields_update y devuelve el pedido guardado bajo order al checkout. La respuesta del comercio anterior contiene los tres campos de actualización; la respuesta al checkout contiene el pedido con los demás campos conservados. Si se aplican otras promociones, consérvalas en la lista de descuentos devuelta y recalcula los totales. Devuelve una lista vacía y un descuento acumulado de cero solo cuando no quede ningún descuento.

Contrato del objeto de descuento

Cada entrada del array de descuentos del pedido describe un descuento aplicado. Usa importes enteros en unidades monetarias menores; una promoción porcentual debe devolver su importe monetario calculado. El contrato de descuentos mapeado admite los siguientes campos:

Campo de descuentoTipo JSONSignificado
amountintegerImporte monetario aplicado por este descuento.
code, referencestringCódigo de promoción e identificador de referencia del comercio.
description, details_urlstringDescripción y enlace opcional a los detalles de la promoción.
typestringTipo de descuento: order_value, product, o free_shipping.
discount_categorystringClasificación del descuento definida por el comercio.
target_typestringComponente de destino, cuando corresponda: item o shipping.
free_shippingobjectDetalles de la promoción de envío: is_free_shipping es un booleano; maximum_cost_allowed es un entero en unidades monetarias menores.

Estos campos describen el resultado de tu lógica de promoción; no configuran los BIN elegibles ni hacen que DEUNA calcule un descuento. Incluye los campos exigidos por el contrato acordado. Las listas de descuentos de artículos y envío usan objetos de referencia que contienen amount y ref_idx; no repiten el objeto completo de descuento del pedido. Mantén esas referencias coherentes con los descuentos del pedido devueltos.

Ante un fallo de cálculo o procesamiento, devuelve un estado HTTP distinto de 2xx. Sin un mapeo de errores personalizado, usa el cuerpo de error que se muestra a continuación. El estado ilustra un fallo temporal y el código de error lo define el comercio:

Respuesta de error del comercioHTTP
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "code": "PROMOTION_UNAVAILABLE",
  "message": "Unable to calculate the card promotion."
}

Acuerda una error_response_template si tu endpoint usa otra estructura de error. Una tarjeta no elegible es un resultado normal sin descuento, no un fallo de procesamiento. El checkout debe seguir el comportamiento ante fallos acordado en el paso 5, en lugar de asumir que se ha aplicado un descuento.

Ejemplo de cálculo de propina

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

Diagrama de secuencia
1Shopper + checkoutUI2DEUNA3Backend delcomerciotip_amount_updated + ordertokenSigned request with order +tip inputRecalculated total + tipfieldValidate response andapply permittedupdatesUpdated order + tip resultDisplay the new total
Comercio o clienteDEUNA

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 prueba#

Probar notificaciones de estado

Probar un webhook dinámico

Prueba un descuento por tarjeta

Completa las comprobaciones del webhook dinámico y verifica el flujo de introducción de la tarjeta antes de habilitar la promoción en producción:

En esta sección