Webhooks
Reciba notificaciones firmadas del estado de pago e integre devoluciones de llamada configurables en el checkout.
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.
| Flujo | Cuándo se ejecuta | Úselo para |
|---|---|---|
| Notificación del estado del pedido y del pago | Después de que cambia un estado de pago suscrito | Actualice el estado de cumplimiento, conciliación y pedido del cliente sin hacer sondeos continuos. |
| Webhook dinámico de checkout | Mientras el checkout espera una respuesta del comerciante | Aplica 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.
Estado de pagoy DEUNA verifica la suscripción del comercio.Configurar entrega de estados
Defina el contrato de entrega para cada entorno:
| Configuración | Qué definir |
|---|---|
| Destino | El endpoint HTTPS que acepta notificaciones de estado. |
| Eventos | El payment.<status> eventos requeridos por su ciclo de vida de pedido. |
| Contrato de solicitud | Cualquier encabezado estático, parámetro de URL y transformación de carga útil aprobada. |
| Manejo de fallos | El 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 :
{
"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.
- Lea el cuerpo de la solicitud sin modificar antes de que un framework lo analice o reserialice.
- Aplique el procedimiento de verificación HMAC-SHA256 y Base64 certificado para el flujo y entorno de entrega.
- Compare el valor calculado con
X-Signatureusando una comparación de tiempo constante. - 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
- Verifique la firma antes de confiar en la carga útil.
- Registre una clave de deduplicación que incluya el token del pedido y el evento o estado de pago resultante.
- Devuelva una respuesta exitosa de
2xxtan pronto como la solicitud sea aceptada de manera duradera. - Vuelva a leer o concilie el estado autoritativo del pedido antes de un cumplimiento, cancelación, captura, reembolso u otra acción irreversible.
- 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.
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ón | Requisito | Qué controla |
|---|---|---|
event_name | Requerido | Nombre de evento específico del comercio que usa letras, números, guiones o guiones bajos. Configura su activador por separado. |
url | Requerido | Destino del endpoint del comercio. Usa HTTPS para la integración. |
http_method | Opcional | Método HTTP: GET, POST, PUT, o PATCH. El valor predeterminado es POST. |
headers | Opcional | Array de pares de key y value para encabezados adicionales de la solicitud. Los valores pueden usar plantillas del pedido. |
params, query_params | Opcional | Arrays 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_template | Opcional | Construye 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_template | Opcional | Mapea el JSON del comercio al contrato de respuesta del pedido. Omítela si tu endpoint ya devuelve ese contrato. |
response_data | Obligatorio con response_template | JSON 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_template | Opcional | Mapea un formato alternativo de error del comercio. Sin esta plantilla, las respuestas de error del comercio usan code y message. |
fields_update.fields | Opcional | Array 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_fields | Opcional | Array 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.fields | Obligatorio al crear la configuración | Acepta 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_fields | Opcional | Array de nombres de campos personalizados declarados que se incluyen en el resultado del checkout. Es independiente del permiso para actualizar esos campos. |
propagate_response | Opcional | El 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.fields | Datos de la respuesta del comercio | Comportamiento de actualización |
|---|---|---|
TotalAmount | order.total_amount | Reemplaza el total a pagar. |
TotalDiscount | order.total_discount | Reemplaza el importe total de descuento. |
Discounts | order.discounts | Reemplaza todo el array de descuentos del pedido. |
Items.TotalAmount | order.items[].id, order.items[].total_amount | Busca los artículos existentes por ID y actualiza su importe, importe original y descuento total. |
Items.Discounts | order.items[].id, order.items[].discounts | Busca los artículos existentes por ID y reemplaza sus referencias de descuentos. |
Shipping | order.shipping | Reemplaza 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:
{
"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
| Preocupación | Requisito del endpoint del comerciante |
|---|---|
| Ejecución repetida | Procesa de forma idempotente los datos repetidos. Recalcula cuando cambien los datos de la promoción. |
| Contrato de respuesta | Devolver JSON que coincida con la forma de respuesta configurada o la plantilla de respuesta. |
| Campos obligatorios | Incluye todos los campos de actualización configurados, incluidos los valores cero al eliminar un descuento. |
| Latencia | Completar dentro del tiempo de espera certificado para la integración porque el checkout espera la respuesta. |
| Errores | Devolver 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.
Configura e implementa este flujo en cada entorno:
- 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.
- 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,
onCardBinDetectedexponecardBinycardBrand; consulta la referencia de callbacks del Web SDK. El callback del cliente y el webhook entre servidores son pasos separados. - 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.
- 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.
- 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:
{
"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.
{
"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"
}'const response = await fetch("https://merchant.example.com/checkout/card-discounts", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
body: JSON.stringify({
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
})
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();import requests
response = requests.request(
"POST",
"https://merchant.example.com/checkout/card-discounts",
headers={
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
json={
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
},
)
response.raise_for_status()
data = response.json()<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://merchant.example.com/checkout/card-discounts",
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Signature: SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation: OPERATION_FROM_DEUNA"
],
CURLOPT_POSTFIELDS => json_encode([
"order_token" => "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id" => "merchant-order-123",
"currency" => "USD",
"total_amount" => 10000,
"cardBin" => "411111",
"cardBrand" => "visa"
])
]);
$response = curl_exec($curl);
curl_close($curl);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("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")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
}
}package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
request, err := http.NewRequest("POST", "https://merchant.example.com/checkout/card-discounts", strings.NewReader("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
if err != nil { panic(err) }
request.Header.Set("Content-Type", "application/json")
request.Header.Set("X-Signature", "SIGNATURE_FROM_DEUNA")
request.Header.Set("X-Deuna-Operation", "OPERATION_FROM_DEUNA")
response, err := http.DefaultClient.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}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:
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 respuesta | Tipo JSON | Obligatorio en este ejemplo | Significado |
|---|---|---|---|
order.total_amount | integer | Sí | Total final a pagar en unidades menores de la moneda, después del descuento. |
order.total_discount | integer | Sí | Descuento total en las mismas unidades, incluida la promoción por tarjeta. |
order.discounts | array de objetos | Sí | 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:
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 descuento | Tipo JSON | Significado |
|---|---|---|
amount | integer | Importe monetario aplicado por este descuento. |
code, reference | string | Código de promoción e identificador de referencia del comercio. |
description, details_url | string | Descripción y enlace opcional a los detalles de la promoción. |
type | string | Tipo de descuento: order_value, product, o free_shipping. |
discount_category | string | Clasificación del descuento definida por el comercio. |
target_type | string | Componente de destino, cuando corresponda: item o shipping. |
free_shipping | object | Detalles 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:
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.
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: