- Getting Started
- Tutorials
- Reference
- API Reference
- Basic Payment
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Corporate
- Merchant
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Brands Reference
- API Reference
- FAQ
- Imprint

Webhooks Integration Guide
Notification content and structure
The notification body contains the type of notification and its payload.
{ "type": [notification_type], "action": [status], "payload": [content] }
Parameter | Description | Format | Required |
---|---|---|---|
type | Type of the notification
|
(PAYMENT|REGISTRATION|RISK) | required |
action |
Indicator of status change. This field is available only if the type is REGISTRATION.
|
(CREATED|UPDATED|DELETED) | conditional |
payload | Content of the notification. If the notification type is payment or registration, the payload's content will be identical to the response you received on the payment or registration. | JSON | required |
Example - payment
{ "type":"PAYMENT", "payload":{ "id":"8a829449515d198b01517d5601df5584", "paymentType":"PA", "paymentBrand":"VISA", "amount":"92.00", "currency":"EUR", "presentationAmount":"92.00", "presentationCurrency":"EUR", "descriptor":"3017.7139.1650 OPP_Channel ", "result":{ "code":"000.100.110", "description":"Request successfully processed in 'Merchant in Integrator Test Mode'" }, "authentication":{ "entityId":"8a8294185282b95b01528382b4940245" }, "card":{ "bin":"420000", "last4Digits":"0000", "holder":"Jane Jones", "expiryMonth":"05", "expiryYear":"2018" }, "customer":{ "givenName":"Jones", "surname":"Jane", "merchantCustomerId":"jjones", "sex":"F", "email":"jane@jones.com" }, "customParameters":{ "SHOPPER_promoCode":"AT052" }, "risk":{ "score":"0" }, "buildNumber":"ec3c704170e54f6d7cf86c6f1969b20f6d855ce5@2015-12-01 12:20:39 +0000", "timestamp":"2015-12-07 16:46:07+0000", "ndc":"8a8294174b7ecb28014b9699220015ca_66b12f658442479c8ca66166c4999e78" } }
Example - registration
{ "type":"REGISTRATION", "action": "CREATED", "payload":{ "id":"8a82944a53e6a0150153eaf693584262", "paymentBrand":"VISA", "result":{ "code":"000.100.110", "description":"Request successfully processed in 'Merchant in Integrator Test Mode'", "randomField1315125026":"Please allow for new unexpected fields to be added" }, "card":{ "bin":"420000", "last4Digits":"0000", "holder":"Jane Jones" }, "authentication":{ "entityId":"8a8294174b7ecb28014b9699220015ca" }, "redirect":{ "parameters":[ ] }, "risk":{ "score":"" }, "timestamp":"2016-04-06 09:45:41+0000", "ndc":"8a8294174b7ecb28014b9699220015ca_b1539494024c411684b544574716e608" } }
Example - risk
{ "type": "RISK", "payload": { "id": "8ac9a4a86461239601646522acb26523", "referencedId": "8ac9a4a86461239601646522aaf96510", "paymentType": "RI", "paymentBrand": "VISA", "presentationAmount": "0.0", "result": { "code": "000.000.000", "description": "Transaction succeeded" }, "card": { "bin": "420000", "last4Digits": "0000", "holder": "Jane Jones", "expiryMonth": "03", "expiryYear": "2025" }, "authentication": { "entityId": "8a8294174b7ecb28014b9699220015ca" }, "redirect": { "parameters": [] }, "risk": { "score": "" }, "timestamp": "2018-07-04 11:52:08+0000", "ndc": "8a8294174b7ecb28014b9699220015ca_b1539494024c411684b544574716e608" } }
Encryption
The content of notification is encrypted to protect data from fraud attempts. When converting human-readable string to hexadecimal format, we use UTF-8.
Parameter | Description |
---|---|
Encryption algorithm | AES |
Key | [secret of listener] (64-character-long hexadecimal string in configuration) |
Key length | 256 bits (32 bytes) |
Block mode | GCM |
Padding | None |
Initialization vector | In HTTP header (X-Initialization-Vector) |
Authentication tag | In HTTP header (X-Authentication-Tag) |
Format of body: Hexadecimal
Format of Initialization Vector: Hexadecimal
Example
Payload {"type": "PAYMENT"} Payload in Hexadecimal (after getting bytes in UTF-8) 7B2274797065223A20225041594D454E54227D Key in Hexadecimal 000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F Initialization-Vector (Hexadecimal) 3D575574536D450F71AC76D8 Authentication-Tag (Hexadecimal) 19FDD068C6F383C173D3A906F7BD1D83 Encrypted value in Hexadecimal F8E2F759E528CB69375E51DB2AF9B53734E393
Responding to Notifications
When your service receives a webhook notification, it must return a 2xx HTTP status code. Otherwise, the webhook service considers the notification delivery as failed, and will retry to send the notification later.
Protocol Details
Protocol | HTTPS (HTTP is allowed on test systems only) |
HTTP method | POST |
Content type | text(text/plain) |