Webhoook Event Notification

Notifications, often referred to as webhooks, provide a mechanism for applications to receive real-time updates about specific events. Within this API, webhooks are used to inform your server about a range of events, including transactions, refunds, or card tokenization, allowing your system to react promptly to these occurrences.

Notification / Webhook URL must be provided beforehand so that traffic can be allowed.

Security

To validate the authenticity of requests, we use a signature process. The API key is hashed using SHA-256 to generate a key, which is then used in a HMAC-SHA-256 operation to sign the timestamp (Sec-Timestamp header) and request body. The signature is then compared to the value sent in the Sec-Signature header. Additionally, after verifying the signature, you must retrieve the session object to ensure the accuracy and legitimacy of the event before further processing. Note that you should expect to receive multiple events and handle each one accordingly.

key = SHA256(secretAPIKey)
time = request.header.Get('Sec-Timestamp')
hmac = HMAC-SHA-256(time + request.body, key)
if hmac == request.header.Get('Sec-Signature') {
    echo "Signature is valid"
}    

Resending of notifications

The webhook must return a status code within the 2xx range. If a different status code is received, the system will make 4 retry attempts. After the 4th attempt, it will continue retrying with an exponential backoff for up to 3 days.

Webhoook Event Object

Field	Type	Description
id	string	Unique identifier for the event object.
type	enum	The event type is either “session.created”, “session.expired”, “session.completed”, “refund.created”, “refund.failed”, “refund.succeeded”. Events starting with “refund.” are refund events.
version	string	The API version used to render the event data.
created_at	int	The Unix timestamp (in seconds) when the event was created.
data.status	enum	Present only for session events (event type starts with “session."). The status of the session. One of: “open”, “expired”, or “completed”.
data.session_id	string	Unique identifier for the session object associated to the event. Present in both session and refund events.
data.refund_id	string	Present only for refund events (event type starts with “refund."). The unique identifier of the refund object associated with the event.
data.refund_status	enum	Present only for refund events (event type starts with “refund."). The status of the refund. One of: “pending”, “succeeded”, or “failed”.

Session Creation Notification

The "session.created" notification informs your system that a new session has been successfully created

The above event type returns JSON structured like this:

{
  "id": "AZIGaeLbem2YK9tJu-hlIg",
  "version": "0.1",
  "type": "session.created",
  "create_at": 1726684455,
  "data": {
    "session_id": "AZIGaeLRdVWAenLbf0FhyA",
    "status": "open"
  }
}

Session Complete Notification

The "session.completed" notification informs your system that a new session has been successfully completed

The above event type returns JSON structured like this:

{
  "id": "AZICl7zwcWy-RRgcTH0mbQ",
  "version": "0.1",
  "type": "session.completed",
  "create_at": 1726620351,
  "data": {
    "session_id": "AZIClyFieTev7xCi6JuXBQ",
    "status": "completed"
  }
}

Session Expire Notification

The "session.expired" notification informs your system that a new session has been expired

The above event type returns JSON structured like this:

{
  "id": "AZIF2O__eJSHRFuYCX18ag",
  "version": "0.1",
  "type": "session.expired",
  "create_at": 1726674956,
  "data": {
    "session_id": "AZIF2O-zdqO1BTTr6V0opw",
    "status": "expired"
  }
}