Webhook (comunicación online)

Cuando se realiza una operación (pago, OCT, Subscription), nuestro sistema notifica automáticamente a tu backend mediante una llamada HTTP POST a la URL de webhook configurada. Esto te permite sincronizar el estado final de cada transacción en tu sistema, incluso si la operación falla.

¿Cómo funciona?

• Cada operación procesada genera un evento de confirmación.

• El backend recibe un payload JSON con los datos de la transacción.

• Si la operación incluye una tokenización, se incluye un bloque tokenData.

¿Cómo se garantiza la identidad e integridad del mensaje?

Cuando se notifica a tu comercio sobre el resultado de una operación, se incluye una cabecera HTTP llamada X-Wipay-Signature. Esta firma tiene como propósito validar la identidad de WiPay como fuente legítima de la información y asegurar que el mensaje no ha sido alterado.

La firma es de tipo HMAC, generada con el algoritmo SHA-256 y codificada en Base64. Se calcula siguiendo estos pasos:

Tener en cuenta que el orden de los campos concatenados es esencial.

1. Concatenar los siguientes campos del mensaje, en este orden: merchantId + requestId + status + amount + currency.

2. Utilizar la clave secreta del comercio para construir una llave usando el algoritmo HmacSHA256.

3. Aplicar la función HMAC sobre la concatenación de los campos usando la llave generada.

4. Codificar el resultado en Base64.

Este valor puede ser validado por tu sistema para confirmar que el mensaje proviene efectivamente de WiPay y que su contenido es íntegro.

Se aconseja implementar un mecanismo adicional de protección contra ataques de fuerza bruta basados en análisis de tiempo de respuesta (ataques por timestamp o "timing attacks"). Estos ataques buscan adivinar la clave secreta del comercio realizando múltiples solicitudes y analizando diferencias mínimas en el tiempo de procesamiento.

Para mitigar esto, se recomienda:

• Utilizar una comparación de firmas constante en tiempo (constant-time comparison).

• Limitar la cantidad de intentos de verificación permitidos por unidad de tiempo.

• Registrar y monitorear intentos fallidos para detectar patrones de comportamiento sospechoso.

Campos Clave

Header	Descripción
X-Wipay-Signature	Firma de autenticidad

Campo	Descripción
requestId	ID único de la operación.
status	Resultado de la operación: OK o KO.
paymentMethodData	Información parcial del método de pago usado.
tokenData	Solo si se generó un token (tokenización).
reference	Referencia única del procesador.
finalStateDate	Fecha y hora final de estado de la transacción.

Webhook de Payment

Información de la comunicación

Si la operación conllevaba una tokenización, la comunicación agregará la información relacionada en 'tokenData'

Cuando se confirma un pago, nuestro sistema envía una notificación como esta:

Ejemplo de Payload – Payment

OK

{
  "requestId": "980002372-25-0-IHaojWNB7-WubnbpeQvd7UBJ",
  "merchantOperationId": "123",
  "userId": "[email protected]",
  "amount": 1,
  "currency": "978",
  "language": "1",
  "merchantId": "980002372",
  "operationType": "PAYMENT",
  "status": "OK",
  "reference": "1200124793250701183959007100",
  "finalStateDate": "2025-07-01T16:40:09.495Z",
  "paymentMethodData": {
    "entityType": "PaymentCardMethodData",
    "method": "CARD",
    "methodDescription": "**** **** **** 5108",
    "authorizationNumber": "474873",
    "cardNumber": null,
    "finalPAN": "5108",
    "brand": "VISA",
    "issuerBank": null,
    "BIN8": "45076700"
  },
  "tokenData": {
    "tokenId": "980016141-25-y5QaJMbTqGNj3Kd2svgJsTkC",
    "expirationDate": "2025-10-01T00:01:00.005Z",
    "tokenType": "CARD"
  }
}

KO

Webhook de OCT

Cuando se confirma una operación de tipo OCT (Original Credit Transaction, por ejemplo devoluciones o pagos directos a tarjetas), se envía un webhook similar pero específico.

Ejemplo de Payload – OCT

{
  "requestId": "980002372-25-0-OCTexample",
  "userId": "[email protected]",
  "amount": 100,
  "currency": "978",
  "merchantId": "980002372",
  "operationType": "OCT",
  "status": "OK",
  "reference": "1200124793250701183959007100",
  "finalStateDate": "2025-07-01T17:00:09.495Z",
  "paymentMethodData": {
    "method": "CARD",
    "methodDescription": "**** **** **** 1234",
    "finalPAN": "1234",
    "brand": "VISA",
    "authorizationNumber": "567890"
  }
}

Webhook de Subscription

Notifica automáticamente al comercio sobre cambios de estado de suscripciones a través de una URL predefinida.

Los estados a notificar son lo siguientes:

• Subscripción → Activa

• Subscripción → Cancelada

• Fin subscripción → Inactiva

Ejemplo de Payload – Subscription

OK ACTIVE

{
    "subscriptionId": "980002372-25-e9826152-9d66-49bb-b067-b9e6d69d357b",
    "userId": "user3",
    "amount": 2.06,
    "currency": "978",
    "totalCycles": 2,
    "currentCycle": 0,
    "status": "ACTIVE",
    "language": "es",
    "startDate": "2025-07-29T23:00:00.000Z",
    "endDate": "2025-07-31T23:00:00.000Z"
}

OK INACTIVE

KO