- Get Started
- Guides
- Integrations
- References
- API Reference
- Basic Payment
- Forex
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Corporate
- Sender
- Recipient
- Merchant
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Job
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- API Reference
- Support
Payload
Last updated:April 11th, 2024
Notification content and structure
The notification body contains the type of the notification and its payload.
{ "type": [notification_type], "action": [status], "payload": [content] }
Parameter | Description | Format | Required |
---|---|---|---|
type | Type of the notification sent.
|
(PAYMENT|REGISTRATION|SCHEDULE|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. The payload's content is expected to be identical to the response you received on the payment, registration, scheduling or standalone risk transaction. | 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.000.000", "description":"Transaction succeeded" }, "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", "channelName": "OPP_Channel", "source": "SYSTEM", "paymentMethod": "CC", "shortId": "5420.6916.5424" } }
Example - registration
{ "type":"REGISTRATION", "action": "CREATED", "payload":{ "id":"8a82944a53e6a0150153eaf693584262", "paymentBrand":"VISA", "result":{ "code":"000.000.000", "description":"Transaction succeeded", "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", "channelName": "OPP_Channel", "source": "SYSTEM", "paymentMethod": "CC", "shortId": "7820.6916.2918" } }
Example - schedule
{ "type": "SCHEDULE", "payload": { "id": "8acda4a489919d63018996faf10b2a66", "registrationId": "8acda4a889919e5e018996f86a8f127a", "paymentType": "SD", "presentationAmount": "92.00", "presentationCurrency": "EUR", "result": { "code": "000.000.000", "description": "Transaction succeeded", "randomField1730751282": "Please allow for new unexpected fields to be added" }, "resultDetails": { "ConnectorTxID1": "8acda4a489919d63018996faf10b2a66" }, "customer": { "givenName":"Jones", "surname":"Jane", "merchantCustomerId":"jjones", "sex":"F", "email":"jane@jones.com" }, "authentication": { "entityId": "8a8294174b7ecb28014b9699220015ca" }, "redirect": { "parameters": [] }, "risk": { "score": "" }, "timestamp": "2023-07-27 10:52:55+0000", "ndc": "ef2c099f5b29455a9dbd260c59bcc224", "channelName": "OPP_Channel", "source": "SCHEDULER", "paymentMethod": "DC", "shortId": "3833.0396.7654" } }
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", "channelName": "OPP_Channel", "source": "SYSTEM", "paymentMethod": "RM", "shortId": "3833.0396.7654" } }
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 sending the notification later according to the retry interval.
Protocol Details
Protocol | HTTPS (HTTP is allowed on test systems only) with TLSv1.2 |
HTTP method | POST |
Content type | text(text/plain) |
For PCI DSS compliance, SSL (Secure Socket Layers) connections using untrusted certificates are not allowed.
Please ensure you have a valid SSL certificate chain. Self-signed certificates are not valid.