Webhooks Integration Guide

Webhooks Integration Guide

Notification content and structure

The notification body contains the type of the notification and its payload.

{
	"type": [notification_type],
	"action": [status],
	"payload": [content]
}
ParameterDescriptionFormatRequired
type Type of the notification sent.
  • PAYMENT: when a payment is created or updated in the system.
  • REGISTRATION: when a registration is created or deleted.
  • SCHEDULE: when a scheduler is created or deleted.
  • RISK: when a risk transaction is created or updated.
 (PAYMENT|REGISTRATION|SCHEDULE|RISK) required
action Indicator of status change. This field is available only if the type is REGISTRATION.
  • CREATED when registration has been created.
  • UPDATED when registration has been updated.
  • DELETED when registration has been deleted.
 (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.

ParameterDescription
Encryption algorithmAES
Key[secret of listener] (64-character-long hexadecimal string in configuration)
Key length256 bits (32 bytes)
Block modeGCM
PaddingNone
Initialization vectorIn HTTP header (X-Initialization-Vector)
Authentication tagIn 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 or TLSv1.3
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.

See also