Webhook Definition
In order to notify the customer about the change of status or result of any payment, the customer should expose a Webhook with the following definition, please remember that the nature of webhook is asynchronous, no payload is expected as a result of sending you the event, only a 200 Status Code. Any code different from 200 will be interpreted as a missing attempt to inform you and will enter into a repetition cycle, please read the next section to acknowledge the amount of repetitions and spacing between them.
Due to the nature of each payment channel different data is available for each type of payment, although, there are shared parameters across the different events. As for now, three different events have been defined.
- SPEI-IN Notification
- SPEI-OUT Notification
- Credit/Debit Notification
The Customer can provide to KANDU different URI for each event
Base Data Structure (shared elements)
This elements will always be available for all WebHook events
Field | DataType | Description | Length |
|---|---|---|---|
eventId | UUID | Unique ID for this specific notification/event. | |
type | String | Type of operation. | 20 |
data | Object | (see definition below) | |
data | Object | (see definition below) | |
data | Object | (see definition below) |
"Data" Object Definition
At this point in time, Data only contains a Transaction Object, but for future use it could contain information not related to a transaction but rather to an administrative event.
| Field | DataType | Description |
|---|---|---|
| Transaction | Object |
"Transaction" Object Definition
This Object contains the information related to a financial transaction, the parameters are shared across any transaction that has a financial impact.
| Field | DataType | Description | Length |
|---|---|---|---|
| transactionId | UUID | Is the UUID Generated by the Merchant to identify his transaction (only avaiable when the transaction is originated by the Merchant) | |
| orderId | UUID | Is the UUID Generated for the transaction at Kandu | |
| merchantId | UUID | The UUID assigned by Kandu to the merchant | |
| customerReference | String | Your customer user label (the way you identify it) e.g. your player id | 50 |
| requestedAt | DateTime | Timestamp (UTC) when the request was first received. | 24 |
| dateTime | DateTime | Timestamp (UTC) for the Webhook event. | 24 |
| amount | Decimal | The monetary value of the transaction in the corresponding currency of the transaction. Supports decimals. | |
| currency | String | 3-letter currency code. Available currencies: "MXN" | 3 |
| status | String | Current state of the transaction. See details of available status here. | 32 |
"Details" Object Definition for SPEI-IN and SPEI-OUT
Please note that this object contains two objects related to the sender and the recipient of the payment
| Field | DataType | Description | Length |
|---|---|---|---|
| concept | String | Description field in a SPEI transaction | 32 |
| referenceNumber | String | Reference field in a SPEI transaction | 7 |
| trackingKey | String | The official "Clave de Rastreo" to track via Banxico (CEP). | 32 |
| sender | object | Information related to the sender of the payment | |
| recipient | object | Information related to the recipient of the payment |
"Details.Sender" Object Definition
| Field | DataType | Description | Lenght |
|---|---|---|---|
| clabe | String | The 18-digit CLABE of the source account. | 18 |
| name | String | Name of the account holder of the source CLABE | 128 |
| rfc | String | RFC (TaxId) of the account holder of the source CLABE | 13 |
"Details.Recipient" Object Definition
| Field | DataType | Description | Length |
|---|---|---|---|
| clabe | String | The 18-digit CLABE of the recipient account. "UN" for unknown. | 18 |
| name | String | RFC (TaxId) of the account holder of the recipient CLABE "UN" for unknown. | 128 |
| rfc | String | The 18-digit CLABE of the receiver account "UN" for unknown. ****ND | 13 |
Repetitions Pattern
Upon failure of the Webhook interface of the Customer (different from SC 200) Kandu will attempt to inform in a repetition pattern to inform the customer of an event.
| Attempt | Seconds |
|---|---|
| 1 | 0 |
| 2 | 30 |
| 3 | 60 |
| 4 | 120 |
| 5 | 180 |
| 6 | 300 |
| 7 | 600 |