Links

Webhooks

Cardknox accounts can be configured to send notifications, known as webhooks, to a designated URL each time a transaction is processed on the account. These webhooks are sent as a series of key-value pairs, encoded in a POST request, and contain all the necessary information to identify the transaction and its status. The information included in these webhooks can be customized to fit your needs, and a complete list of available fields can be found in the "Response Parameters" section.

Host

52.39.85.5 52.39.84.254

HTTP Request Method

POST

content-type

application/x-www-form-urlencoded; charset=utf-8
See example below:
Form values
​
xEnteredDate
9/3/2021 9:28:22 AM
xRefNum
506918667
xCommand
CC:Sale
xAmount
0.01
xResponseResult
Approved
xMaskedCardNumber
4xxxxxxxxxxx1111
xExp
1020
xCardType
Visa
xToken
7h39p8qp6hq2pgqp76mgg2qnq7npp3g5
xSoftwareName
KnockKnox
xSourceKey
Cardknox Support Key
xResponseBatch
6358090
xMerchantID
8663
xMerchantName
Cardknox Support
Raw Content xEnteredDate=9%2f3%2f2021+9%3a28%3a22+AM&xRefNum=506918667&xCommand=CC%3aSale&xAmount=0.01&xResponseResult=Approved&xMaskedCardNumber=4xxxxxxxxxxx1111&xExp=1020&xCardType=Visa&xToken=7h39p8qp6hq2pgqp76mgg2qnq7npp3g5&xSoftwareName=KnockKnox&xSourceKey=Cardknox+Support+Key&xResponseBatch=6358090&xMerchantID=8663&xMerchantName=Cardknox+Support

Webhook PIN

The Cardknox Gateway uses webhooks to send real-time notifications about transactions. To ensure the authenticity of these notifications and protect against DDoS attacks, a PIN can be set up in the Cardknox backend by a support representative.
Cardknox generates a unique signature to authenticate webhooks it sends, by:
  1. 1.
    Sorting the response parameters (key-value pairs) in alphabetical order based on the key name.
  2. 2.
    Extracting the values while preserving the order.
  3. 3.
    Appending the PIN to the string of values.
  4. 4.
    Hashing the string using the MD5 method.
The signature is included in the webhook header as ck-signature. To verify the authenticity of the webhook on the recipient's end, the same steps used by Cardknox to generate the signature should be repeated, and the result should be compared to the "ck-signature" sent by Cardknox. If the two signatures match, it means that the webhook was indeed sent by Cardknox.

IPN PIN

IPN PIN Guidelines:
  • The pin can only be AlphaNumeric
  • The pin must be at least 15 characters long
How it works:
The dynamo setting IPN_CustomTransactionFields must be set and include xSignature as one of the requested fields. When an IPN is sent, besides for just the transaction response being sent in the body, a signature would be sent in the header as an added security measure. This signature is generated based on the values of the response fields and the PIN set in the IPN_PIN setting. Together these values are hashed (MD5) to create a signature.
This signature can then be verified dynamically on the user’s end based on the transaction response that is sent to the webpage.
Examples:
Transaction response: xRefNum=326942315&xAmount=1.00&xSignature=&xRequestAmount=1.00&xReviewed=N
Transaction response values, sorted alphabetically by transaction response keys: 1.003269423151.00N
We would then concatenate 1.003269423151.00N with the IPN_Pin value, hash it, and store the hash in the header under ck-signature. The example below displays a sample postback with signature.
IPN PIN Example
Last modified 20d ago