documentation
Search…
Integration Guide

Notification content and structure:

The notification body contains the type of notification and its payload:
1
{
2
"type": [notification_type],
3
"action": [status],
4
"payload": [content]
5
}
Copied!
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.
(PAYMENT|REGISTRATION)
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

Payload Examples

Payment
Registration
1
"type":"PAYMENT",
2
"payload":{
3
"id":"8a829449515d198b01517d5601df5584",
4
"paymentType":"PA",
5
"paymentBrand":"VISA",
6
"amount":"92.00",
7
"currency":"EUR",
8
"descriptor":"3017.7139.1650 OPP_Channel ",
9
"result":{
10
"code":"000.100.110",
11
"description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
12
},
13
"authentication":{
14
"entityId":"8a8294185282b95b01528382b4940245"
15
},
16
"card":{
17
"bin":"420000",
18
"last4Digits":"0000",
19
"holder":"Jane Jones",
20
"expiryMonth":"05",
21
"expiryYear":"2018"
22
},
23
"customer":{
24
"givenName":"Jones",
25
"surname":"Jane",
26
"merchantCustomerId":"jjones",
27
"sex":"F",
28
29
},
30
"customParameters":{
31
"SHOPPER_promoCode":"AT052"
32
},
33
"risk":{
34
"score":"0"
35
},
36
"buildNumber":"[email protected] 12:20:39 +0000",
37
"timestamp":"2015-12-07 16:46:07+0000",
38
"ndc":"8a8294174b7ecb28014b9699220015ca_66b12f658442479c8ca66166c4999e78"
39
}
40
}
Copied!
1
{
2
"type":"REGISTRATION",
3
"action": "CREATED",
4
"payload":{
5
"id":"8a82944a53e6a0150153eaf693584262",
6
"paymentBrand":"VISA",
7
"result":{
8
"code":"000.100.110",
9
"description":"Request successfully processed in 'Merchant in Integrator Test Mode'",
10
"randomField1315125026":"Please allow for new unexpected fields to be added"
11
},
12
"card":{
13
"bin":"420000",
14
"last4Digits":"0000",
15
"holder":"Jane Jones"
16
},
17
"authentication":{
18
"entityId":"8a8294174b7ecb28014b9699220015ca"
19
},
20
"redirect":{
21
"parameters":[
22
23
]
24
},
25
"risk":{
26
"score":""
27
},
28
"timestamp":"2016-04-06 09:45:41+0000",
29
"ndc":"8a8294174b7ecb28014b9699220015ca_b1539494024c411684b544574716e608"
30
}
31
}
Copied!

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

1
Payload
2
{"type": "PAYMENT"}
3
4
Payload in Hexadecimal (after getting bytes in UTF-8)
5
7B2274797065223A20225041594D454E54227D
6
7
Key in Hexadecimal
8
000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F
9
10
Initialization-Vector (Hexadecimal)
11
3D575574536D450F71AC76D8
12
13
Authentication-Tag (Hexadecimal)
14
19FDD068C6F383C173D3A906F7BD1D83
15
16
Encrypted value in Hexadecimal
17
F8E2F759E528CB69375E51DB2AF9B53734E393
Copied!

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)

Decryption Examples

C#
Java
PHP
Python
1
using System;
2
using System.Linq;
3
using System.Text;
4
using Org.BouncyCastle.Crypto.Engines;
5
using Org.BouncyCastle.Crypto.Modes;
6
using Org.BouncyCastle.Crypto.Parameters;
7
8
namespace DecryptionExample
9
{
10
// You need to install bccrypto-csharp from BouncyCastle. Please see BouncyCastle page.
11
class Program
12
{
13
static void Main(string[] args)
14
{
15
string keyFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
16
17
// Data from server
18
string ivFromHttpHeader = "000000000000000000000000";
19
string authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD";
20
string httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
21
22
// Convert data to process
23
byte[] key = ToByteArray(keyFromConfiguration);
24
byte[] iv = ToByteArray(ivFromHttpHeader);
25
byte[] authTag = ToByteArray(authTagFromHttpHeader);
26
byte[] encryptedText = ToByteArray(httpBody);
27
byte[] cipherText = encryptedText.Concat(authTag).ToArray();
28
29
// Prepare decryption
30
GcmBlockCipher cipher = new GcmBlockCipher(new AesFastEngine());
31
AeadParameters parameters = new AeadParameters(new KeyParameter(key), 128, iv);
32
cipher.Init(false, parameters);
33
34
// Decrypt
35
var plainText = new byte[cipher.GetOutputSize(cipherText.Length)];
36
var len = cipher.ProcessBytes(cipherText, 0, cipherText.Length, plainText, 0);
37
cipher.DoFinal(plainText, len);
38
Console.WriteLine(Encoding.ASCII.GetString(plainText));
39
}
40
41
static byte[] ToByteArray(string HexString)
42
{
43
int NumberChars = HexString.Length;
44
byte[] bytes = new byte[NumberChars / 2];
45
for (int i = 0; i < NumberChars; i += 2)
46
{
47
bytes[i / 2] = Convert.ToByte(HexString.Substring(i, 2), 16);
48
}
49
return bytes;
50
}
51
}
52
}
Copied!
1
import com.google.common.base.Charsets;
2
import org.apache.commons.lang3.ArrayUtils;
3
import org.bouncycastle.jce.provider.BouncyCastleProvider;
4
import javax.crypto.Cipher;
5
import javax.crypto.spec.IvParameterSpec;
6
import javax.crypto.spec.SecretKeySpec;
7
import javax.xml.bind.DatatypeConverter;
8
import java.security.Security;
9
10
// For Java and JVM-based languages, you might need to install unrestricted policy file for JVM,
11
// which is provided by Sun. Please refer BouncyCastle FAQ if you get
12
// java.lang.SecurityException: Unsupported keysize or algorithm parameters or
13
// java.security.InvalidKeyException: Illegal key size.
14
15
// If you cannot install unrestricted policy file for JVM because of some reason, you can try with reflection: See here.
16
17
public class Decryption
18
{
19
public static void main(String[] args) throws Exception
20
{
21
Security.addProvider(new BouncyCastleProvider());
22
23
// Data from configuration
24
String keyFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
25
26
// Data from server
27
String ivFromHttpHeader = "000000000000000000000000";
28
String authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD";
29
String httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
30
31
// Convert data to process
32
byte[] key = DatatypeConverter.parseHexBinary(keyFromConfiguration);
33
byte[] iv = DatatypeConverter.parseHexBinary(ivFromHttpHeader);
34
byte[] authTag = DatatypeConverter.parseHexBinary(authTagFromHttpHeader);
35
byte[] encryptedText = DatatypeConverter.parseHexBinary(httpBody);
36
37
// Unlike other programming language, We have to append auth tag at the end of encrypted text in Java
38
byte[] cipherText = ArrayUtils.addAll(encryptedText, authTag);
39
40
// Prepare decryption
41
SecretKeySpec keySpec = new SecretKeySpec(key, 0, 32, "AES");
42
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
43
cipher.init(Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(iv));
44
45
// Decrypt
46
byte[] bytes = cipher.doFinal(cipherText);
47
System.out.println(new String(bytes, Charsets.UTF_8));
48
}
49
}
Copied!
1
<?php
2
/* Please refer Using Libsodium in PHP Projects */
3
$key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
4
$iv_from_http_header = "000000000000000000000000";
5
$auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD";
6
$http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
7
8
$key = hex2bin($key_from_configuration);
9
$iv = hex2bin($iv_from_http_header);
10
$cipher_text = hex2bin($http_body . $auth_tag_from_http_header);
11
12
$result = \Sodium\crypto_aead_aes256gcm_decrypt($cipher_text, NULL, $iv, $key);
13
print($result);
14
?>
Copied!
1
import os
2
import binascii
3
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
4
from cryptography.hazmat.backends import default_backend
5
6
# Data from configuration
7
key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f"
8
9
# Data from server
10
iv_from_http_header = "000000000000000000000000"
11
auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD"
12
http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9"
13
14
# Convert data to process
15
key = binascii.unhexlify(key_from_configuration)
16
iv = binascii.unhexlify(iv_from_http_header)
17
auth_tag = binascii.unhexlify(auth_tag_from_http_header)
18
cipher_text = binascii.unhexlify(http_body)
19
20
# Prepare decryption
21
decryptor = Cipher(algorithms.AES(key), modes.GCM(iv, auth_tag), backend = default_backend()).decryptor()
22
23
# Decrypt
24
result = decryptor.update(cipher_text) + decryptor.finalize()
25
print(result)
Copied!
Last modified 2yr ago