Get gateway webhook notifications

You can receive notifications about card registrations and payments from the CardCorp gateway webhook. This document describes how to prepare your server, configure the webhook notifications, and how to decrypt and read the events.

📘
CardCorp Gateway Documentation
This document is a summary of the CardCorp gateway documentation on webhooks. The request examples and code samples are quoted directly from that documentation. For the full page with more details and code samples, see https://docs.oppwa.com/tutorials/webhooks

Prepare your HTTPS server

Prepare an HTTPS server to listen for POST requests from the gateway as follows:

For security, use TLS 1.2 or higher and add a valid, trusted certificate (not self signed)
Configure it to use caching to asynchronously process a large number of requests at peak traffic times
Prepare the server to decrypt the events (see below)
Prepare to possibly receive events with a delay or out of sequence
Check the transaction ID and status in case there is more than one message for a single transaction
Send a 2XX HTTP response code to confirm successful receipt of each request

Configure the webhook

To configure the webhook, contact the CardCorp Merchant Services Team

Give the Merchant Services team the following:
1. The URL of your HTTPS server
2. A fallback email in case the gateway detects that your server is not receiving notifications
Get the key for decrypting the notifications
By default, the gateway sends the events in a JSON wrapper. This means the POST request uses Content-Type: application/json and body format: {"encryptedBody": "hexadecimal_string"}). Tell the CardCorp Merchant Services team if you want to receive a plain text body with the hexadecimal string.

Decrypt the webhook notification

To decrypt the request:

Use the secret key from CardCorp Merchant Services team
Read the hexadecimal string from the notification. If it is JSON format, get it from the encryptedBody field.
Read the initialization vector and authentication tag from the HTTP headers (X-Initialization-Vector (hexadecimal) and X-Authentication-Tag (hexadecimal).
Decrypt the hexadecimal string using AES-256-GCM. The data is in JSON format
Check the authentication tag from the header matches the one in the decrypted JSON
Read the event data from the decrypted JSON.

Here are some examples of decryption code.

var crypto = require("crypto");
 
// Data from configuration
var secretFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
 
// Data from server
var ivfromHttpHeader = "000000000000000000000000";
var authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD";
var httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
 
// Convert data to process
var key = new Buffer(secretFromConfiguration, "hex");
var iv = new Buffer(ivfromHttpHeader, "hex");
var authTag = new Buffer(authTagFromHttpHeader, "hex");
var cipherText = new Buffer(httpBody, "hex");
 
// Prepare descryption
var decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
decipher.setAuthTag(authTag);
 
// Decrypt
var result = decipher.update(cipherText) + decipher.final();
console.log(result);

<?php
/* Php 7.1 or later */
    $key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
    $iv_from_http_header = "000000000000000000000000";
    $auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD";
    $http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
    
    $key = hex2bin($key_from_configuration);
    $iv = hex2bin($iv_from_http_header);
    $auth_tag = hex2bin($auth_tag_from_http_header);
    $cipher_text = hex2bin($http_body);
    
    $result = openssl_decrypt($cipher_text, "aes-256-gcm", $key, OPENSSL_RAW_DATA, $iv, $auth_tag);
    print($result);
    
/* Php prior to 7.1 */
    /* Please refer Using Libsodium in PHP Projects */
    $key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
    $iv_from_http_header = "000000000000000000000000";
    $auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD";
    $http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
    
    $key = hex2bin($key_from_configuration);
    $iv = hex2bin($iv_from_http_header);
    $cipher_text = hex2bin($http_body . $auth_tag_from_http_header);
    
    $result = \Sodium\crypto_aead_aes256gcm_decrypt($cipher_text, NULL, $iv, $key);
    print($result);
?>

Webhook event format

After decryption, the events have this basic JSON format.

{
	"type": [PAYMENT or REGISTRATION],
	"action": [for REGISTRATION only: CREATED, UPDATED, DELETED],
	"payload": [Event content like the API response for payment or registration]
}

Each section contains additional information according to the individual transaction.

Here are examples from the gateway documentation for the payment and registration events.

Gateway example for 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":"[email protected]"
      },
      "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"
  }
}

Gateway example for 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"
   }
}