Webhooks

Kushki envía notificaciones de webhook a tu servidor por cada evento de transacción presencial: cargos, anulaciones y reembolsos. Tu endpoint recibe el payload del evento poco después de que la terminal confirma la operación.

Configuración

Los webhooks de pagos presenciales se configuran desde la Kushki Console, en Desarrolladores → Webhooks. La configuración de webhooks por API no está soportada para pagos presenciales.

Seguridad

Cifrado

Puedes usar una URL HTTP o HTTPS para los webhooks. En general HTTP es suficiente, pero se recomienda HTTPS si manejas datos sensibles o quieres protegerte contra ataques de repetición.

Autenticación

Cualquiera podría, en principio, enviar una petición a tu endpoint, así que es importante verificar que una notificación realmente proviene de Kushki. Los webhooks válidos contienen estas cabeceras:

Cabecera	Descripción
`X-Kushki-Key`	ID Kushki del comercio (lo encuentras en la Console, en Perfil → Servicios).
`X-Kushki-Id`	Fecha en formato timestamp Unix.
`X-Kushki-Signature`	Hex digest HMAC-SHA256 del body de la petición concatenado con `X-Kushki-Id`, firmado con tu ID de firma de Webhook.
`X-Kushki-SimpleSignature`	Hex digest HMAC-SHA256 solo de `X-Kushki-Id`, firmado con tu ID de firma de Webhook.

Puedes usar X-Kushki-Signature o X-Kushki-SimpleSignature para verificar la autenticidad: compara el valor de la cabecera con la firma que calculas de tu lado usando tu ID de firma de Webhook.

Dónde encontrar tu ID de firma de Webhook

Console → Perfil → Servicios → Identificadores → Webhook Signature.

IPs de origen

Kushki envía las notificaciones de webhook desde estas IPs estáticas; puedes usarlas como capa adicional de validación:

Entorno	IP
Sandbox (UAT)	`54.208.105.247`
Producción	`34.230.185.20`

Verificación de la firma

Node.js — X-Kushki-Signature (cuerpo + timestamp):

Node.js — X-Kushki-SimpleSignature (solo timestamp):

WARNING

Verifica siempre la firma antes de confiar en el payload. Rechaza cualquier petición en la que la verificación falle.

Idempotencia

Kushki almacena las notificaciones en varios servidores para lograr alta disponibilidad. En casos poco frecuentes podrías recibir la misma notificación más de una vez.

WARNING

Diseña tu manejador de webhooks para que sea idempotente: procesar la misma notificación dos veces no debe producir efectos duplicados.

Payload del webhook

Kushki reutiliza el mismo mecanismo de webhooks que las transacciones con tarjeta en general. La forma del payload cambia según el evento:

Eventos de cargo (aprobado o rechazado)

Los nombres de campo van en snake_case.

{
  "ticket_number": "111727462978861299",
  "transaction_id": "821730184348805573736",
  "transaction_reference": "0c291739-d93a-4e89-9b44-6de011c4fdb8",
  "amount": {
    "subtotalIva0": 10000,
    "subtotalIva": 0,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "currency_code": "CLP",
  "transaction_type": "SALE",
  "transaction_status": "APPROVAL",
  "created": 1727462978861,
  "merchant_id": "20000000109815430000",
  "merchant_name": "Mi Comercio Chile",
  "processor_id": "6000000000167692716389681607",
  "processor_name": "Kushki Acquirer Processor",
  "processor_type": "gateway",
  "last_four_digits": "5480",
  "approval_code": "676300",
  "request_amount": 10000,
  "approved_transaction_amount": 10000,
  "response_code": "000",
  "response_text": "Transacción aprobada",
  "card_holder_name": "Catalina Fuentes",
  "payment_brand": "MASTERCARD",
  "card_type": "credit",
  "issuing_bank": "BANCO SANTANDER CHILE",
  "foreign_card": false,
  "bin_card": "521892",
  "token": "dffddf9aa77549148d2450d0662c6e4b",
  "credential_alias": "Producción Chile",
  "credential_id": "45fe3a3ebe464ebb100f2aa344b6a095"
}

transaction_type siempre es "SALE" en una notificación de cargo. transaction_status es "APPROVAL" o "DECLINED".

Eventos de anulación y reembolso

Los nombres de campo van en camelCase, una convención distinta a la de los eventos de cargo.

{
  "ticketNumber": "661738684712571670",
  "transactionId": "700011575252919092",
  "transactionReference": "2052742c-97dc-4d8a-b7b0-27bf4eafcc0a",
  "amount": {
    "subtotalIva0": 0,
    "subtotalIva": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "currencyCode": "CLP",
  "transactionType": "VOID",
  "transactionStatus": "APPROVAL",
  "created": 1738684712892,
  "merchantId": "20000000109815430000",
  "merchantName": "Mi Comercio Chile",
  "processorId": "6000000000172166121420424728",
  "processorName": "Kushki Acquirer Processor",
  "processorType": "gateway",
  "lastFourDigits": "5480",
  "approvalCode": "000000",
  "requestAmount": 10000,
  "approvedTransactionAmount": 10000,
  "cardHolderName": "Catalina Fuentes",
  "paymentBrand": "MASTERCARD",
  "cardType": "credit",
  "binCard": "521892",
  "foreignCard": false,
  "voidTicketNumber": "661738684712571670",
  "saleTicketNumber": "029184246439606168",
  "saleApprovalCode": "000000"
}

transactionType es "VOID" o "REFUND". transactionStatus es "APPROVAL".

Prueba tu webhook

Las interacciones entre endpoints en internet pueden ser complicadas: verifica que tu webhook funcione correctamente antes de liberarlo a producción.

Revisa el estado de tu webhook

Desde la Kushki Console, ve a Desarrolladores → Webhooks para ver la lista de los webhooks que has creado, con la fecha de creación, el alias, el producto o medio de pago para el que está configurado y su estado de conexión (Exitosa o Fallida). Haz clic en la etiqueta de estado de conexión para ver la URL y los eventos configurados para ese webhook.

Simula una notificación de prueba

Haz clic en Simular conexión en cualquier webhook para enviarle una notificación de prueba: elige el medio de pago o producto, el evento y el código correspondiente a simular.

Agrega cabeceras personalizadas

Puedes agregar hasta 4 cabeceras personalizadas a cualquier webhook, además de las cabeceras que Kushki envía por defecto:

Haz clic en el ícono de editar junto al webhook.

Agrega una etiqueta y un valor para tu cabecera y haz clic en Guardar Webhook.

Haz clic en + para agregar otra cabecera (hasta 4 en total).

Buenas prácticas

Responde rápido. Devuelve un HTTP 2xx en cuanto recibas la notificación, antes de ejecutar tu lógica de negocio; procesa de forma asíncrona si lo necesitas.

Diseña para la idempotencia. Usa ticket_number / ticketNumber como llave de deduplicación.

Verifica la firma en cada petición. No confíes en el payload hasta que X-Kushki-Signature o X-Kushki-SimpleSignature cuadre.

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Seguridad#

Cifrado#

Autenticación#

IPs de origen#

Verificación de la firma#

Idempotencia#

Payload del webhook#

Eventos de cargo (aprobado o rechazado)#

Eventos de anulación y reembolso#

Prueba tu webhook#

Revisa el estado de tu webhook#

Simula una notificación de prueba#

Agrega cabeceras personalizadas#

Buenas prácticas#

Seguridad

Cifrado

Autenticación

IPs de origen

Verificación de la firma

Idempotencia

Payload del webhook

Eventos de cargo (aprobado o rechazado)

Eventos de anulación y reembolso

Prueba tu webhook

Revisa el estado de tu webhook

Simula una notificación de prueba

Agrega cabeceras personalizadas

Buenas prácticas