Webhook (Online Communication)

When an operation (payment or OCT) is performed, our system automatically notifies your backend via an HTTP POST call to the configured webhook URL. This allows you to synchronize the final status of each transaction in your system, even if the operation fails.

How is the identity and integrity of the message ensured?

When your system is notified about the result of an operation, an HTTP header called X-Wipay-Signature is included. This signature serves to validate Wipay’s identity as the legitimate source of the information and to ensure that the message has not been tampered with.

The signature is of type HMAC, generated using the SHA-256 algorithm and encoded in Base64. It is calculated by following these steps:

The order of the concatenated fields is essential.

1. Concatenate the following message fields in this order: merchantId + requestId + status + amount + currency.

2. Use the merchant's secret key to construct a key using the HmacSHA256 algorithm.

3. Apply the HMAC function to the concatenated string using the generated key.

4. Encode the result in Base64.

This value can be validated by your system to confirm that the message truly comes from Wipay and that its content is intact.

It is recommended to implement an additional protection mechanism against brute-force attacks based on response time analysis (timestamp or "timing attacks"). These attacks attempt to guess the merchant’s secret key by making multiple requests and analyzing minimal differences in processing time.

To mitigate this risk, it is recommended to:

• Use constant-time signature comparison.

• Limit the number of verification attempts allowed per time unit.

• Log and monitor failed attempts to detect suspicious behavior patterns.

Key Fields

Header	Description
X-Wipay-Signature	Authenticity signature

Field	Description
requestId	Unique operation ID identifier
status	Operation result: OK o KO.
paymentMethodData	Partial payment method information
tokenData	Only if a Token was generated (Tokenization)
reference	Unique processor reference
finalStateDate	Operation status and final date

Payment Webhook

Endpoint: POST /webhook/cecabank/payment/{statusInfo}

Communication Information

If the operation involved tokenization, the notification will include related data in the tokenData field.

When a payment is confirmed, our system sends a notification with the following format:

Example Payload – Payment (Success)

jsonCopyEdit{
  "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"
  }
}

Example Payload – Payment (Failure)

jsonCopyEdit{
  "requestId": "980002372-25-0-MFMDwuzl3ib6X84hgabxm1xF",
  "merchantOperationId": "123",
  "userId": "",
  "amount": 2,
  "currency": "978",
  "language": "es",
  "merchantId": "980002372",
  "operationType": "PAYMENT",
  "status": "KO",
  "customError": {
    "errorCode": "U003",
    "description": "Card issuer denied operation"
  },
  "terminalId": "00000003",
  "reference": "",
  "finalStateDate": "2025-07-16T15:15:01.243Z"
}

---

OCT Webhook

Endpoint: POST /webhook/cecabank/oct/{statusInfo}

When an OCT (Original Credit Transaction — e.g., direct payments to cards) is confirmed, a similar but specific webhook is sent.

Example Payload – OCT

jsonCopyEdit{
  "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"
  }
}