Webhooks
A webhook is an API that providers near real-time information. PayTel uses webhooks to inform the merchants regarding changes on a Transaction payment status.
The Merchant can receive the notifications either by email or endpoint (notification assembling to the status inquiry – Checkout Status), however only a notification will be sent for each transaction.
Notifications are sent by endpoint straight to the URL configured by the Merchant. The parameterization of this endpoint needs to be done on the Gateway BackOffice.
Learn how to create a webhook on the Gateway BackOffice.
Each time that Gateway receives an update on the payment status of a transaction a notification will be sent with the new transaction payment status.
Every day a summarized email with the most recent failed notifications, is sent by the Gateway (email needs to be registered on the BackOffice).
There is no guarantee on the order of messages, especially if the time difference between the notifications is smaller than the time it takes to process them or by any communication or systems issues. Once the issues are sort out, new notifications will arrive in real time and old notifications would be resent. In case no notification is received the option “Checkout Status” should be used before rejecting any transaction.
Notifications are sent as HTTP callbacks (webhooks) to an endpoint on your server. Please ensure you have a valid SSL certificate chain. Self-signed certificates are not valid.
To receive notifications, you need a server that has:
- An endpoint that can receive an HTTP POST.
- An open TCP port for HTTPS traffic (443, 80) with TLSv1.2.
Depending on your network and security requirements, you might also need to add our network to your firewall’s whitelist.
To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with an HTTP 200 and a response containing:
{
“statusCode”: “200”,
“statusMsg”: “Success”,
“notificationID”: “2533e456-5e36-42c8-9eea-7961902f185e”
}
When your server receives a notification it should:
- Decrypt the notification
- Store the notification in your database.
- Acknowledge the notification with an HTTP 200 OK and the following response body:
{ "statusCode": "200", "statusMsg": "Success","notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" }
Decrypt
The content of notification is encrypted to protect data from fraud attempts. When converting human-readable string to hexadecimal format, we use UTF-8.
- Encryption algorithm : AES
- Block mode : GCM
- Padding : None
- Initialization vector : In HTTP header (X-Initialization-Vector)
- Authentication tag : In HTTP header (X-Authentication-Tag)
Format of body: Base64 Format of Initialization Vector: Base64
Examples
Below there are 4 examples of how to decrypt the webhook notification
|