PrimeiroPay
Search…
⌃K

Webhook 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 This type of notification is sent when a payment is created or updated in the system.
  • REGISTRATION This type of notification is sent when a registration is created or deleted.
  • RISK This type of notification is sent when a risk transaction is created or deleted.
(PAYMENT|REGISTRATION|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. 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":"[email protected]"
},
"customParameters":{
"SHOPPER_promoCode":"AT052"
},
"risk":{
"score":"0"
},
"buildNumber":"[email protected] 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"
}
}
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)
Previous
Webhook
Next
Examples for decrypting message
Last modified 2yr ago