Overview
NOTE: Instant Notification Service (INS) is intended to be used by people who have programming experience. If you don't have programming experience, we encourage you to reach out to someone who does to assist you with this feature.
ClickBank offers an Instant Notification Service that notifies you of transactions within the ClickBank system for your account. It sends data to you in a near real-time fashion for the following events:
Sale which is the sale of a standard product or initial sale of a recurring product.
Rebill which is a rebill for a recurring product.
Refund which is a refund for a standard or recurring product.
Chargeback which is a chargeback for a standard or recurring product.
Cancel Rebill which is the canceling of a recurring product.
Un-cancel Rebill which is the reversal of a recurring product cancellation by a ClickBank customer service representative.
Subscription Change which is a product change in an existing subscription.
Cart Abandonment which occurs when a customer abandoning a cart, if you have the Cart Abandonment feature enabled. NOTE: This is available in versions 6.0 and later.
Test Transactions which occurs when test transactions for the types listed above, or a test of the instant notification feature that you initiate.
If you don't understand all of these steps, we recommend that you enlist the services of a developer who can help you. If you implement Instant Notifications incorrectly, we may disable or remove the feature from your account.
The following sections are included in this article:
Secret Key
The service attempts to post information via HTML FORM POST to a URL specified by you. Each post contains a group of URL Parameters relevant to the transaction. The notification is encrypted, and must be decrypted using your secret key and the initialization vector before it can be processed.
Once enabled, the Instant Notification service is triggered every time a transaction is created or an action is taken upon a transaction in your ClickBank account.
The primary flow involves the following steps:
An action occurs in the ClickBank system (such as a sale or rebill).
Clickbank encrypts a notification using your secret key and an initialization vector.
ClickBank posts HTML FORM parameters to a URL you specify.
Your URL should use Transport Layer Security (TLS) or Secure Socket Layer (SSL).ClickBank uses Response Code Monitoring to verify that the notification was received.
An application you build decrypts the message (using your secret key and the initialization vector) and processes the post parameters.
Setting up the service on your ClickBank account is straightforward. However, you must also build an application that processes the instant notification URL parameters, which is a more technical task. In order to make good use of this service, your application must, at a minimum, decrypt the message and process the parameters outlined in the Parameters section of this document.
Current Version
The current version of the Instant Notification feature is 8.0. It is nearly identical to version 7.0 but with additional data fields. New features and fields in version 8.0 include:
commonTrackingParameters
The common tracking parameters array contains request data that is automatically collected and stored by ClickBank, including timestamps, click IDs, device information, operating system details, browser information, and more. The common request data is accessible to both Affiliate and Vendor role types. Fields in the array may include:
clickId
Unique id for the hop or order form impression if there is no attributed hop
clickTimestamp
Timestamp of the initial hop or order form impression event if there is no attributed hopdeviceType
Type of devicedeviceModel
Model of device
deviceBrand
Brand of deviceos
Operating system of device
osVersion
Operating system version of devicebrowser
Browser name of devicebrowserVersion
Browser version of devicebrowserLang
Browser language of deviceuseragent
User agent of the requesting devicetrackingType
The tracking type indicates if attribution was provided based on a click from a HopLink, Direct Tracking Link, or from the Affiliate fallback methodcbPage
If applicable, the 'cbpage' parameter applied to the HopLink which redirects the click to the alternative HopLink landing page defined within the ClickBank platform
affiliateTrackingParameters
The affiliate tracking parameters array contains the affiliate tracking parameters field and values appended to the affiliate's HopLink or Direct Tracking Link when applicable. Tracking parameters which are not used will not be returned in the INS message.
Note: affiliate tracking parameter data is only accessible to the affiliate role type.
See the Legacy Versions section for information about the parameters used by older versions. Some older versions of Instant Notification do not encrypt the notification, so we do not recommend use of versions earlier than 6.0.
Notification Format
This section describes the format of the instant notification sent to you.
Base Structure
Instant Notifications are created in the JSON format. They are encrypted prior to sending.
The base structure of an instant notification is:
{"notification": "<ENCRYPTED_NOTIFICATION>", "iv": "<INITIALIZATION_VECTOR>"}
Encryption
ClickBank uses the CBC-AES-256 encryption algorithm to secure the payload of the notification. This helps prevent customer information from being passed in clear text, and allows the receiver of the notification to know that the message originated from ClickBank and was not altered during delivery. The notification is encrypted using a secret key, of up to 16 characters, and an initialization vector.
Several examples of how to decrypt the notification are listed in the Code Samples section, but you should familiarize yourself with the AES-256 encryption algorithm to have a better understanding of how it works.
The initial JSON message contains a string representation of the encrypted notification, and the initialization vector which you can use in parallel with your ClickBank secret key to decrypt the notification.
Parameters
This section describes all of the parameters used in a notification. When a notification is sent, it includes all parameters. If a parameter contains no value, the instant notification string contains the parameter tag without a value. This is why the number of characters for some parameters includes zero, as these parameters may not contain a value. All currency amounts are presented in USD.
Header Parameters
Parameter | Description | Characters / Format | Recipient |
transactionTime | Time of transaction in ISO 8601 format | 25 | All |
receipt | ClickBank receipt ID | 8-21 | All |
transactionType | The type of transaction. | 4-31 – See Transaction Types | All |
vendor | The vendor nickname | 5-10 | All |
affiliate | The affiliate nickname. | 5-10 | All |
role | Your role in the transaction | 6-9 – VENDOR, AFFILIATE, or JV_UPSELL | All |
totalAccountAmount | Total you received for the transaction in USD | Numeric with 2 decimal precision | All |
paymentMethod | Payment method used by the customer. | 3-4 – See Payment Methods | All |
totalOrderAmount | Total the customer was charged | Numeric with 2 decimal precision | All |
totalTaxAmount | Total the customer paid in taxes | Numeric with 2 decimal precision | Vendor |
totalShippingAmount | Total the customer paid in shipping | Numeric with 2 decimal precision | Vendor |
currency | Currency the user paid in | 3 | Vendor |
orderLanguage | Language used on the order form | 2 – DE, EN, ES, FR, IT, or PT | Vendor |
trackingCodes | Any tracking codes passed into the order form. | 0-100 each | Vendor, Affiliate |
declinedConsent | Indicates whether the customer declined consent for marketing communications under GDPR. | 3-5 – See GDPR Consent Status | Vendor |
Product Parameters
Parameter | Description | Characters / Format | Recipient |
itemNo | SKU of the product ordered | 1-25 | All |
productTitle | Product title | 0-255 | All |
productPrice | Base price for this item, including exchange rates but not including discounts, taxes, or shipping | Numeric with 2 decimal precision | All |
productDiscount | The discount amount applied to the product | Numeric with 2 decimal precision | All |
jvPayout | The total amount of | Numeric with 2 decimal precision | All |
affiliatePayout | The amount earned by the affiliate for the sale of the product | Numeric with 2 decimal precision | Vendor |
taxAmount | The tax the customer paid on the product | Numeric with 2 decimal precision | All |
shippingAmount | The shipping & handling fees paid by the customer | Numeric with 2 decimal precision | All |
shippingLiable | Whether you receive the shipping & handling fees | 4-5 – true or false | All |
shippable | Whether the product was a physical good | 4-5 – true or false | All |
recurring | Whether the product was subscription-based | 4-5 – true or false | All |
accountAmount | Amount you received on this line item | Numeric with 2 decimal precision | All |
quantity | Quantity of item purchased | Numeric | All |
downloadUrl | Product download URL for the customer | 0-255 | Vendor |
lineItemType | Type of order the line item was part of | 4-8 – ORIGINAL, CART, BUMP, or UPSELL | All |
Customer Shipping Parameters
Parameter | Description | Characters | Recipient |
firstName | Customer's first name | 0-255 | Vendor |
lastName | Customer's last name | 0-255 | Vendor |
fullName | Customer's first and last name | 0-255 | Vendor |
phoneNumber | Customer's phone number | 0-255 | Vendor |
Customer's email address | 0-255 | Vendor | |
address1 | Customer's physical address, line 1 | 0-255 | Vendor |
address2 | Customer's physical address, line 2 | 0-255 | Vendor |
city | Customer's city | 0-255 | Vendor |
county | Customer's county | 0-255 | Vendor |
state | Customer's state | 0-255 | Vendor |
postalCode | Customer's postal code or zip code | 0-255 | Vendor |
country | Customer's country | 0-255 | Vendor |
Customer Billing Parameters
Parameter | Description | Characters | Recipient |
firstName | Customer's first name | 0-255 | Vendor |
lastName | Customer's last name | 0-255 | Vendor |
fullName | Customer's first and last name | 0-255 | Vendor |
phoneNumber | Customer's phone number | 0-255 | Vendor |
Customer's email address | 0-255 | Vendor | |
state | Customer's state | 0-255 | All |
postalCode | Customer's postal code or zip code | 0-255 | All |
country | Customer's country | 0-255 | All |
Upsell Parameters
Parameter | Description | Characters | Recipient |
upsellOriginalReceipt | Receipt number that started the upsell flow | 8-21 | All |
upsellFlowId | ID of the upsell flow | Integer | Vendor |
upsellSession | Session ID for the upsell | 0-16 | Vendor |
upsellPath | Upsell path | 0-12 | Vendor |
Affiliate Tracking Parameters
Parameter | Description | Characters | Recipient |
trafficType | Parameter designed to pass the channel type or category of traffic where the user engaged | 0-100 | Affiliate |
trafficSource | Parameter designed to pass the source channel or platform of the traffic | 0-100 | Affiliate |
offer | Parameter designed to pass an offer name, identifier | 0-100 | Affiliate |
campaign | Parameter designed to pass a campaign name or identifier | 0-100 | Affiliate |
ad | Parameter designed to pass information about the ad the user engaged with | 0-150 | Affiliate |
adgroup | Parameter designed to pass information about the adgroup the ad the user engaged with | 0-100 | Affiliate |
creative | Parameter designed to pass information about the creative used in promotional content the user engaged with | 0-150 | Affiliate |
affSub1 -affSub5 | Parameters designed to pass non-unique data which may not fall into any of the named and commonly tracked data. For example, a client may want to analyze the conversion rate across different email sends, and use an aff_sub parameter to pass an identifier for each email send. | 0-100 | Affiliate |
extclid | Parameter designed to pass a partner or external click identifier | 0-256 | Affiliate |
fbclid | Parameter designed specifically to pass the Facebook clickid, which will be used in ClickBank’s custom facebook integration | 0-256 | Affiliate |
uniqueAffSub1 - uniqueAffSub5 | Parameters designed for affiliates to pass unique data of the click, session, user, etc. that will be available in transaction level reporting | 0-256 | Affiliate |
Common Request Data
Parameter | Description | Characters | Recipient |
clickTimestamp | Timestamp of the initial hop or order form impression event if there is no attributed hop. Example: 2023-10-02T12:34:20.093332Z | 0-50 | All |
clickId | Unique id for the hop or order form impression | 0-100 | All |
deviceType | Type of device | 0-50 | All |
deviceBrand | Brand of device | 0-50 | All |
deviceModel | Model of device | 0-50 | All |
os | Operating system of device | 0-50 | All |
osVersion | Operating system version of device | 0-50 | All |
browser | Browser name | 0-50 | All |
browserVersion | Browser version | 0-50 | All |
browserLang | Browser language | 0-50 | All |
userAgent | User Agent of device | 0-256 | All |
cbPage | If applicable, the 'cbpage' parameter applied to the HopLink which redirects the click to the alternative HopLink landing page defined within the ClickBank platform | 0-50 | All |
trackingType | The tracking type indicates if attribution was provided based on a click from a HopLink, Direct Tracking Link, or from the Affiliate fallback method. | 0-50 | All |
Pytch Parameters
NOTE: The Pytch feature has been deprecated, but the parameters are retained for backwards compatibility purposes.
Parameter | Description | Characters / Format | Recipient |
hopfeedClickId | Hopfeed click ID name | String | All |
hopfeedApplicationId | Application ID | Numeric | All |
hopfeedCreativeId | Creative ID | Numeric | All |
hopfeedApplicationPayout | Application Payout | Numeric with 2 decimal precision | All |
hopfeedVendorPayout | Vendor Payout | Numeric with 2 decimal precision | All |
Technical Parameters
Parameter | Description | Format | Recipient |
version | The version of the instant notification. | Double Numeric | All |
attemptCount | The number of times ClickBank tried to send this notification before receiving a success or failing with too many attempts | Integer | All |
Seller Parameters
If the seller has provided any additional variables to the payment link, they are also provided in the notification as parameters called v1, v2, and so on.
Transaction Types
There are a number of values you can receive in the transactionType parameter. These values are listed below with a brief description of their purpose.
NOTE: Notifications for test transactions are only sent to the seller.
Type | Description |
SALE | The purchase of a standard product or the initial purchase of recurring billing product. |
BILL | A rebill for a recurring billing product. |
RFND | The refunding of a standard or recurring billing product. Recurring billing products that are refunded also result in a "CANCEL-REBILL" transaction. |
CGBK | A chargeback for a standard or recurring product. |
INSF | An eCheck chargeback for a standard or recurring product. |
CANCEL-REBILL | The cancellation of a recurring billing product. Recurring billing products that are canceled do not result in any other action. |
UNCANCEL-REBILL | Reversing the cancellation of a recurring billing product. |
SUBSCRIPTION-CHG | A product change for an existing subscription, made through a Master account or through the Orders API. The transaction type header also includes the original and new product SKUs in the following format: |
ABANDONED_ORDER | An abandoned order. Any fields that the customer filled out are included. Fields not filled out by the customer are blank. |
CUSTOMER_AUTH_FAILURE | An authorization failure for a customer's recurring payment. |
CUSTOMER_EMAIL_UPDATE | An update to a customer's email address. |
CUSTOMER_UPDATE_CC_NOTIFICATION | An update to a customer's payment method. |
PURCHASE_DETAILS_EMAIL_RESPONSE | A resending of a customer's receipt email. |
TEST | A test transaction triggered during configuration. |
TEST_BILL | A test rebill for a recurring billing product. |
TEST_RFND | A test refund of a standard or recurring billing product. |
TEST_SALE | A test purchase of a standard or recurring billing product. |
CANCEL-TEST-REBILL | A test recurring product cancelation. |
UNCANCEL-TEST-REBILL | A test cancelation reversal for a recurring product. |
Payment Methods
There are a number of values you can receive in the paymentMethod parameter. These values are listed below.
Payment Method Parameter | Payment Method |
PYPL or PYPL-NEW | PayPal |
VISA | Visa |
MSTR | Mastercard |
DISC | Discover |
AMEX | American Express |
DNRS | Diners Club |
TEST | Test Payment |
GDPR Consent Status
Under the GDPR, European Union customers must actively consent to receive marketing communications. A customer's selection is indicated by the declinedConsent parameter. The values are listed below:
Declined Consent Parameter | Description |
nil | The customer is not in the European Union. |
true | The customer declined to consent to marketing communications. |
false | The customer consented to marketing communications. |
Notification Example
This is a sample of the unencrypted JSON notification showing the structure of the key-value pairs for Version 8.0 of Instant Notification for the affiliate-role.
{
"transactionTime": "2023-10-05T13:47:51-06:00",
"receipt": "TEST0000",
"transactionType": "SALE",
"vendor": "testacct",
"affiliate": "affiliate1",
"role": "AFFILIATE",
"totalAccountAmount": "0",
"paymentMethod": "VISA",
"totalOrderAmount": "0",
"totalTaxAmount": "0",
"totalShippingAmount": "0",
"currency": "USD",
"orderLanguage": "EN",
"trackingCodes": [
"tracking_code"
],
"lineItems": [
{
"itemNo": "1",
"productTitle": "Product Title",
"shippable": false,
"recurring": false,
"accountAmount": "5",
"quantity": "1",
"downloadUrl": "<download_url>",
"lineItemType": "CART"
},
{
"itemNo": "2",
"productTitle": "Second Product",
"shippable": false,
"recurring": true,
"accountAmount": "2.99",
"quantity": "1",
"downloadUrl": "<download_url>",
"lineItemType": "CART"
}
],
"customer": {
"shipping": {
"firstName": "",
"lastName": "",
"fullName": "",
"phoneNumber": "",
"email": "",
"address": {
"address1": "",
"address2": "",
"city": "",
"county": "LAS VEGAS",
"state": "NV",
"postalCode": "89101",
"country": "US"
}
},
"billing": {
"firstName": "",
"lastName": "",
"fullName": "",
"phoneNumber": "",
"email": "",
"address": {
"state": "NV",
"postalCode": "89101",
"country": "US"
}
}
},
"upsell": {
"upsellOriginalReceipt": "XXXXXXXX",
"upsellFlowId": "55",
"upsellSession": "VVVVVVVVVV",
"upsellPath": "upsell_path"
},
"version": "8",
"affiliateTrackingParameters": {
"offer": "myoffer",
"trafficType": "search",
"trafficSource": "google",
"campaign": "mycampaign",
"ad": "testad",
"adgroup": "1",
"creative": "img2",
"extclid": "123",
"fbclid": "456",
"affSub1": "aff_sub1",
"affSub2": "aff_sub2",
"affSub3": "aff_sub3",
"affSub4": "aff_sub4",
"affSub5": "aff_sub5",
"uniqueAffSub1": "unique_aff_sub1",
"uniqueAffSub2": "unique_aff_sub2",
"uniqueAffSub3": "unique_aff_sub3",
"uniqueAffSub4": "unique_aff_sub4",
"uniqueAffSub5": "unique_aff_sub5"
},
"commonTrackingParameters": {
"deviceType": "Desktop",
"osVersion": ">=10.15.7",
"os": "Mac OS",
"trackingType": "hop",
"browserVersion": "16.6",
"browser": "Safari",
"Useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Safari/605.1.15",
"clickId": "16cc1494-8332-40bd-b869-b97357194f12",
"clickTimestamp": "2023-10-02T12:34:20.093332Z",
"deviceModel": "Apple Macintosh",
"deviceBrand": "Apple",
"browserLang": "en"
},
"attemptCount": 1,
"vendorVariables": {
"v1": "variable1",
"v2": "variable2"
}
}
Implementing Instant Notifications
After gaining a sound understanding of the previous section of this document, you can request access to the Instant Notification feature, test your URL, and enable Instant Notifications.
Once you have configured one URL for Instant Notifications, you can add another by using these procedures with the Instant Notification 2 field.
Requesting Access to Instant Notifications
The Instant Notification feature is not automatically enabled. To request access:
Step 1: Log in to your ClickBank account and select the account nickname you want to work in from the Accounts tab.
Step 2: Click the Vendor Settings tab.
Step 3: Click My Site.
Step 4: Find the Advanced Tools section and click Edit.
Step 5: Click the Request Access link next to the Instant Notification URL field.
Step 6: Fill out the form, thoroughly review the terms of use, and acknowledge that you have read and agree to the terms of use.
Step 7: Click the Save Changes & Request API Access button at the bottom of the form.
Step 8: Click the Save Changes button.
Configuring Your URL
Once you have received access to the Instant Notification feature, you must create a target URL and a program to process the Notifications that will be sent to your URL. You can use ports 80 or 443.
Transport Layer Security (TLS) and Secure Socket Layer (SSL)
It is strongly recommended that you utilize this feature with Transport Layer Security (TLS) or Secure Socket Layer (SSL) enabled. Using this feature without TLS or SSL enabled can expose your sales data to thieves. However, because credit card and bank information is not transmitted via the Instant Notification service, we do not require you to use TLS or SSL to encrypt Instant Notification transmissions.
NOTE: You cannot use a self-signed SSL certificate. You must use a valid certificate.
Testing and Enabling Your URL
To enable Instant Notifications, you must enter your Secret Key, test the connectivity and successful processing of the URL parameters between ClickBank and your server, and save your changes.
To test and enable your URL:
Step 1: Log in to your ClickBank account and select the account nickname you want to work in from the Accounts tab.
Step 2: Click the Vendor Settings tab.
Step 3: Click My Site.
Step 4: Find the Advanced Tools section and click Edit.
Step 5: Enter your secret key in the Secret Key field. Your secret key is a string of up to 16 characters, including numbers and capital letters, that you create. Your instant notifications will be encrypted using your secret key. See the Encryption section for more information.
Step 6: Click Save Changes.
Step 7: Find the Advanced Tools section and click Edit.
Step 8: Enter your URL in the Instant Notification URL field.
Step 9: Click Test URL to the right of the URL.
A test notification is sent with a receipt of ******** and a transaction type of TEST.
Review the response to verify that the test was successful.
If the test was successful, the URL is marked as Verified next to the URL field.
If the test was not successful, troubleshoot possible problems with connectivity or your application before retrying. A URL cannot be used until it has been tested successfully.
Step 10: Click Save Changes.
Instant Notification transmissions begin immediately for all verified URLs.
Disabling Instant Notifications
You can disable the feature to prevent notifications from being sent by removing your URL. You can re-enable the feature later.
Step 1: Log in to your ClickBank account and select the account nickname you want to work in from the Accounts tab.
Step 2: Click the Vendor Settings tab.
Step 3: Click My Site.
Step 4: Find the Advanced Tools section and click Edit.
Step 5: Remove the URL from the Instant Notification URL field.
Step 6: Click Save Changes.
Response Code Monitoring
When we send an instant notification, we monitor the response code from your URL. If we receive a response code in the 200 range within 3 seconds, the notification delivery is considered successful.
If the response code is not in the 200 range, we attempt to resend the notification once every four hours. After a max of five failed attempts, it will no longer attempt to deliver the information. There is no way to resend the instant notification once it has reached the max attempts.
Code Samples
The data sent to you by the Instant Notification service is in the form of HTML FORM POST URL Parameters. Programs written within your application architecture must process these pairs. Programs for order management, database activity, and other services may be written but are outside the scope of this guide.
The following code samples cover decrypting the notification.
NOTE: The following code samples must be nested in a program. In addition, these samples will fail if your character set includes German, Greek, Eastern European, or Asian characters. You must perform your own encoding before decrypting instant notifications. If you do not understand, you should find a programmer who can help you.
Java
The following code sample uses Java to decrypt the notification.
public void processNotification(final HttpServletRequest theRequest,
final HttpServletResponse theResponse)
throws IOException {
try {
final StringBuilder buffer = new StringBuilder();
final String secretKey = "YOUR SECRET KEY";
try {
String line;
final BufferedReader reader = theRequest.getReader();
while(null != (line = reader.readLine())) {
buffer.append(line);
}
} catch(final Exception ex) {
ex.printStackTrace();
}
final JSONParser parser = new JSONParser();
final JSONObject obj = (JSONObject) parser.parse(buffer.toString());
final String initializationVector = (String) obj.get("iv");
final String encryptedNotification = (String) obj.get("notification");
final MessageDigest digest = MessageDigest.getInstance("SHA-1");
digest.reset();
digest.update(secretKey.getBytes("UTF-8"));
final String key = new String(Hex.encodeHex(digest.digest())).substring(0, 32);
final IvParameterSpec iv =
new IvParameterSpec(DatatypeConverter.parseBase64Binary(initializationVector));
final SecretKeySpec keySpec = new SecretKeySpec(key.getBytes(), "AES");
final Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.DECRYPT_MODE, keySpec, iv);
final JSONObject notification = (JSONObject) parser.parse(
new String(cipher.doFinal(DatatypeConverter.parseBase64Binary(encryptedNotification)),
"ISO-8859-1"));
//
// Make use of the notification here...
//
} catch(final NoSuchPaddingException
| ParseException
| NoSuchAlgorithmException
| InvalidAlgorithmParameterException
| BadPaddingException
| IllegalBlockSizeException
| UnsupportedEncodingException
| InvalidKeyException ex) {
ex.printStackTrace();
theResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED,
"Could not decrypt instant notification");
}
theResponse.setStatus(HttpServletResponse.SC_NO_CONTENT);
}
PHP
The following code sample uses PHP to decrypt the notification.
<?php
$secretKey = "YOUR SECRET KEY"; // secret key from your ClickBank account
// get JSON from raw body...
$message = json_decode(file_get_contents('php://input'));
// Pull out the encrypted notification and the initialization vector for
// AES/CBC/PKCS5Padding decryption
$encrypted = $message->{'notification'};
$iv = $message->{'iv'};
error_log("IV: $iv");
// decrypt the body...
$decrypted = trim( openssl_decrypt(base64_decode($encrypted), 'AES-256-CBC', substr(sha1($secretKey), 0, 32), OPENSSL_RAW_DATA, base64_decode($iv)), "\0..\32");
error_log("Decrypted: $decrypted");
////UTF8 Encoding, remove escape back slashes, and convert the decrypted string to a JSON object...
$sanitizedData = utf8_encode(stripslashes($decrypted));
$order = json_decode($decrypted);
// Ready to rock and roll - If the decoding of the JSON string wasn't
// successful, then you can assume the notification wasn't encrypted
// with your secret key.
?>
Python
The following code sample uses Python to decrypt the notification.
import hashlib
import json
from Crypto.Cipher import AES
##
# Parse ClickBank Notification
# @param message: A string representing the raw HTTP POST body
# @return: A JSON object representing the decrypted notification
def process_clickbank_notification(message):
j = json.loads(message)
iv = j['iv']
encrypted_str = j['notification']
sha1 = hashlib.sha1()
sha1.update("YOUR SECRET KEY")
cipher = AES.new(sha1.hexdigest()[:32], AES.MODE_CBC, iv.decode('base64'))
return cipher.decrypt(encrypted_str.decode('base64')).strip()
Ruby
The following code sample uses Ruby to decrypt the notification.
require "base64"
require "digest/sha1"
require "json"
require "openssl"
# Decode the IPN post into a JSON object.
# The message param is the raw HTTP POST
# body of the notification
def decrypt_clickbank_notification(message)
parsed = JSON.parse(message);
aes = OpenSSL::Cipher::Cipher.new("AES-256-CBC")
aes.iv = Base64.decode64(parsed["iv"])
aes.decrypt
aes.key = Digest::SHA1.hexdigest("YOUR SECRET KEY").slice(0, 32)
aes.update(Base64.decode64(parsed["notification"])) + aes.final
end
Legacy Versions
This section describes the legacy versions of the instant notification service. If you are using one of these versions, we recommend switching to version 7.0 as soon as possible.
The versions described here do not encrypt the notification, and do not contain some of the parameters included in the latest version.
Cipher
Cipher is a method of performing encryption and decryption. It ensures there has been no URL tampering of the query string parameters.
When an action occurs within your ClickBank account, several values are passed along in the Instant Notification query string. While building the string we create a sha1, or a hash of the values passed, and your Secret Key. The result is the cverify parameter. Upon receipt of the query string parameters, your system must also create a sha1, or a hash of the values passed, and your Secret Key.
The validity of the data received is evaluated by using the cverify parameter we send and the value produced in your system. Only if there is an exact match between the two values can you be certain the information received has not been tampered with.
Please see Legacy Code Samples for examples.
Version 1
The following post parameters are used in Instant Notification Version 1.
Parameter | Description | Details |
caffitid | affiliate TID [only populated for affiliate] | 0 – 100 characters |
ccustcc | customer country code (2-characters) [only populated for vendor] | 0 – 2 characters |
ccustemail | customer email [only populated for vendor] | 1 – 255 characters |
ccustname | customer name as typed in on the order form [only populated for vendor] | 1 – 510 characters |
ccuststate | customer state/province [only populated for vendor] | 0 – 2 characters |
cproditem | product SKU | 1 – 25 characters |
cprodtitle | product title | 0 – 255 characters |
cprodtype | product type (STANDARD, RECURRING) [will also have 'Physical' if the product was a physical good] | 8 – 11 characters |
ctransaction* | transaction type (SALE, JV_SALE, INSF, RFND, CGBK, BILL, JV_BILL, TEST_SALE, TEST_JV_SALE, TEST_BILL, TEST_JV_BILL, TEST_RFND) | 4 – 15 characters |
ctransaffiliate | affiliate nickname | 0 – 10 characters |
ctransamount | amount paid out to the recipient of the notification (in pennies (1000 = $10.00)) | 3 – 10 characters |
ctranspaymentmethod | payment method (AMEX, AUST, BLME, DISC, DNRS, ENRT, IMAS, MAES, MSTR, PYPL, STVA, SWIT, TEST, VISA) | 0 – 4 characters |
ctranspublisher | vendor nickname | 5 – 10 characters |
ctransreceipt | receipt number | 8 – 13 characters |
ctranstime** | the Epoch time the transaction occurred (not included in cverify) | 10 characters |
cupsellreceipt**§ | if this transaction is part of an upsell, this is the originating receipt number. | 8 – 13 characters |
cvendthru | download URL [only populated for vendor] | 0 – 1024 characters |
cverify** | the "cverify" parameter is used to verify the validity of the previous fields | 8 characters |
If product is shippable and recipient is the seller, we will pass the following additional fields:
Parameter | Description | Details |
ccustaddr1** | ship-to address line 1 | 0 – 255 characters |
ccustaddr2** | ship-to address line 2 | 0 – 255 characters |
ccustcity** | ship-to city | 0 – 255 characters |
ccustcounty** | ship-to county | 0 – 255 characters |
ccustshippingcountry** | ship-to country | 0 – 255 characters |
ccustshippingzip** | ship-to zip code | 0 – 255 characters |
ccustzip | customer zip code | 0 – 16 characters |
Version 2
Parameter | Description | Details |
caccountamount | Amount paid to party receiving notification (in pennies (1000 = $10.00)) | 3 – 10 characters |
ccurrency | currency the customer paid in [only populated for vendor] | 2 characters |
ccustaddr1 | ship-to address line 1 [only populated for vendor] | 0 – 255 characters |
ccustaddr2 | ship-to address line 2 [only populated for vendor] | 0 – 255 characters |
ccustcc | customer country code (2-characters) [only populated for vendor] | 0 – 255 characters |
ccustcity | ship-to city [only populated for vendor] | 0 – 255 characters |
ccustcounty | ship-to county [only populated for vendor] | 0 – 255 characters |
ccustemail | customer email [only populated for vendor] | 1 – 255 characters |
ccustfirstname | customer's first name [only populated for vendor] | 1 - 255 characters |
ccustfullname | customer name as typed in on the order form [only populated for vendor] | 1 – 510 characters |
ccustlastname | customer's last name [only populated for vendor] | 1 – 255 characters |
ccustshippingcountry | ship-to country [only populated for vendor] | 0 – 255 characters |
ccustshippingzip | ship-to zip code [only populated for vendor] | 0 – 255 characters |
ccuststate | customer state/province [only populated for vendor] | 0 – 2 characters |
ccustzip | customer zip code [only populated for vendor] | 0 – 16 characters |
cfuturepayments | Number of payments remaining [only populated for recurring products] | 1 – 3 characters |
cnextpaymentdate | Date of next payment (epoch time) [only populated for recurring products] | 8 characters |
corderamount | Order total amount (in pennies (1000 = $10.00)) | 3 – 10 characters |
cprocessedpayments | Number of recurring payments made [only populated for recurring products] | 1 – 3 characters |
cproditem | product SKU | 1 – 25 characters |
cprodtitle | product title | 0 – 255 characters |
cprodtype | product type (STANDARD, RECURRING) [will also have 'Physical' if the product was a physical good] | 8 – 11 characters |
crebillamnt | Recurring payment amount (in pennies (1000 = $10.00)) [only populated for recurring products] | 3 – 10 characters |
crebillstatus | Status of subscription (empty, ACTIVE, COMPLETED, or CANCELED) [only populated for recurring products] | 5 – 9 characters |
ctid | tracking id for the recipient of the notification [only sent to vendor and affiliate, not JV partners] | 0 – 100 characters |
ctransaction* | transaction type (SALE, JV_SALE, INSF, RFND, CGBK, BILL, JV_BILL, TEST_SALE, TEST_JV_SALE, TEST_BILL, TEST_JV_BILL, TEST_RFND) | 4 – 15 characters |
ctransaffiliate | affiliate nickname | 0 – 10 characters |
ctranspaymentmethod | payment method (AMEX, AUST, BLME, DISC, DNRS, ENRT, IMAS, MAES, MSTR, PYPL, STVA, SWIT, TEST, VISA) | 0 – 4 characters |
ctranspublisher | vendor nickname | 5 – 10 characters |
ctransreceipt | receipt number | 8 – 13 characters |
ctransrole | Recipient's role in the transaction (AFFILIATE, VENDOR) | 6 – 9 characters |
ctranstime** | the Epoch time the transaction occurred (not included in cverify) | 10 characters |
cupsellreceipt**§ | if this transaction is part of an upsell, this is the originating receipt number. | 8 – 13 characters |
cvendthru | download URL [only populated for vendor] | 0 – 124 characters |
cverify** | the "cverify" parameter is used to verify the validity of the previous fields | 8 characters |
Version 2.1
Identical to version 2 but adds the following field:
Parameter | Description | Details |
ccustshippingstate | ship-to state/province [only populated for vendor] | 0 – 255 characters |
Version 4
Identical to version 2.1 with the following changes:
Parameter | Description | Details |
cnoticeversion | Version of the notification | 0 – 5 characters |
ctransvendor | vendor nickname (we renamed ctranspublisher) | 5 – 10 characters |
crebillfrequency | frequency of the subscription (weekly, biweekly, monthly, quarterly, yearly) | 0 – 255 characters |
cbfid | ID of the upsell flow [only populated for vendor] | 0 – 11 characters |
cbf | upsell flow session [only populated for vendor] | 0 – 16 characters |
cbfpath | upsell flow path (shows the progress of the upsell flow and the result of each step) [only populated for vendor] | 0 – 12 characters |
corderlanguage | the language select by the customer on the order form [only populated for vendor] | 0 – 2 characters |
ctaxamount | tax amount paid by the customer (in pennies (1000 = $10.00)) [only populated for vendor] | 3 – 10 characters |
cshippingamount | amount of shipping and handling charged (in pennies (1000 = $10.00)) [only populated for vendor] | 3 – 10 characters |
Version 6.0
Version 6.0 includes the following parameters:
Header Parameters
Parameter | Description | Characters / Format | Recipient |
transactionTime | Time of transaction in RFC-3339 format | 25 | All |
receipt | ClickBank receipt ID | 8-21 | All |
transactionType | The type of transaction. | 4-31 – See Transaction Types | All |
vendor | The vendor nickname | 5-10 | All |
affiliate | The affiliate nickname. | 5-10 | All |
role | Your role in the transaction | 6-9 – VENDOR, AFFILIATE, or JV_VENDOR | All |
totalAccountAmount | Total you received for the transaction in USD | Numeric with 2 decimal precision | All |
paymentMethod | Payment method used by the customer. | 3-4 – See Payment Methods | All |
totalOrderAmount | Total the customer was charged | Numeric with 2 decimal precision | All |
totalTaxAmount | Total the customer paid in taxes | Numeric with 2 decimal precision | Vendor |
totalShippingAmount | Total the customer paid in shipping | Numeric with 2 decimal precision | Vendor |
currency | Currency the user paid in | 3 | Vendor |
orderLanguage | Language used on the order form | 2 – DE, EN, ES, FR, IT, or PT | Vendor |
trackingCodes | Any tracking codes passed into the order form. | 0-100 each | Vendor, Affiliate |
paylink | The paylink used to initiate the order Note: This field is only provided if | URL | Vendor |
Product Parameters
Parameter | Description | Characters / Format | Recipient |
itemNo | SKU of the product ordered | 1-25 | All |
productTitle | Product title | 0-255 | All |
shippable | Whether the product was a physical good | 4-5 – true or false | All |
recurring | Whether the product was subscription-based | 4-5 – true or false | All |
accountAmount | Amount you received on this line item | Numeric with 2 decimal precision | All |
quantity | Quantity of item purchased | Numeric | All |
downloadUrl | Product download URL for the customer | 0-255 | Vendor |
lineItemType | Type of order the line item was part of | 4-8 – ORIGINAL, CART, BUMP, TOKEN, or UPSELL | All |
Customer Shipping Parameters
Parameter | Description | Characters | Recipient |
firstName | Customer's first name | 0-255 | Vendor |
lastName | Customer's last name | 0-255 | Vendor |
fullName | Customer's first and last name | 0-255 | Vendor |
phoneNumber | Customer's phone number | 0-255 | Vendor |
Customer's email address | 0-255 | Vendor | |
address1 | Customer's physical address, line 1 | 0-255 | Vendor |
address2 | Customer's physical address, line 2 | 0-255 | Vendor |
city | Customer's city | 0-255 | Vendor |
county | Customer's county | 0-255 | Vendor |
state | Customer's state | 0-255 | Vendor |
postalCode | Customer's postal code or zip code | 0-255 | Vendor |
country | Customer's country | 0-255 | Vendor |
Customer Billing Parameters
Parameter | Description | Characters | Recipient |
firstName | Customer's first name | 0-255 | Vendor |
lastName | Customer's last name | 0-255 | Vendor |
fullName | Customer's first and last name | 0-255 | Vendor |
phoneNumber | Customer's phone number | 0-255 | Vendor |
Customer's email address | 0-255 | Vendor | |
state | Customer's state | 0-255 | All |
postalCode | Customer's postal code or zip code | 0-255 | All |
country | Customer's country | 0-255 | All |
Upsell Parameters
Parameter | Description | Characters | Recipient |
upsellOriginalReceipt | Receipt number that started the upsell flow | 8-21 | All |
upsellFlowId | ID of the upsell flow | Integer | Vendor |
upsellSession | Session ID for the upsell | 0-16 | Vendor |
upsellPath | Upsell path | 0-12 | Vendor |
Pytch Parameters
NOTE: The Pytch feature has been deprecated, but the parameters are retained for backwards compatibility purposes.
Parameter | Description | Characters / Format | Recipient |
hopfeedClickId | Hopfeed click ID name | String | All |
hopfeedApplicationId | Application ID | Numeric | All |
hopfeedCreativeId | Creative ID | Numeric | All |
hopfeedApplicationPayout | Application Payout | Numeric with 2 decimal precision | All |
hopfeedVendorPayout | Vendor Payout | Numeric with 2 decimal precision | All |
Technical Parameters
Parameter | Description | Format | Recipient |
version | The version of the instant notification. | Double Numeric | All |
attemptCount | The number of times ClickBank tried to send this notification before receiving a success or failing with too many attempts | Integer | All |
Seller Parameters
If the seller has provided any additional variables to the payment link, they are also provided in the notification as parameters called v1, v2, and so on.
Transaction Types
There are a number of values you can receive in the transactionType parameter. These values are listed below with a brief description of their purpose.
NOTE: Notifications for test transactions are only sent to the seller.
Type | Description |
SALE | The purchase of a standard product or the initial purchase of recurring billing product. |
BILL | A rebill for a recurring billing product. |
RFND | The refunding of a standard or recurring billing product. Recurring billing products that are refunded also result in a "CANCEL-REBILL" transaction. |
CGBK | A chargeback for a standard or recurring product. |
INSF | An eCheck chargeback for a standard or recurring product. |
CANCEL-REBILL | The cancellation of a recurring billing product. Recurring billing products that are canceled do not result in any other action. |
UNCANCEL-REBILL | Reversing the cancellation of a recurring billing product. |
SUBSCRIPTION-CHG | A product change for an existing subscription, made through a Master account or through the Orders API. The transaction type header also includes the original and new product SKUs in the following format: |
ABANDONED_ORDER | An abandoned order. Any fields that the customer filled out are included. Fields not filled out by the customer are blank. |
CUSTOMER_AUTH_FAILURE | An authorization failure for a customer's recurring payment. |
CUSTOMER_EMAIL_UPDATE | An update to a customer's email address. |
CUSTOMER_UPDATE_CC_NOTIFICATION | An update to a customer's payment method. |
PURCHASE_DETAILS_EMAIL_RESPONSE | A resending of a customer's receipt email. |
TEST | A test transaction triggered during configuration. |
TEST_BILL | A test rebill for a recurring billing product. |
TEST_RFND | A test refund of a standard or recurring billing product. |
TEST_SALE | A test purchase of a standard or recurring billing product. |
CANCEL-TEST-REBILL | A test recurring product cancelation. |
UNCANCEL-TEST-REBILL | A test cancelation reversal for a recurring product. |
Payment Methods
There are a number of values you can receive in the paymentMethod parameter. These values are listed below.
Payment Method Parameter | Payment Method |
PYPL or PYPL-NEW | PayPal |
VISA | Visa |
MSTR | Mastercard |
DISC | Discover |
AMEX | American Express |
DNRS | Diners Club |
TEST | Test Payment |
Version 7.0
Version 7.0 includes the following features and fields upgraded from version 6.0:
productPrice
The price the product is sold to the customer as a line-item per product.productDiscount
Discount applied to the product from a coupon as a line-item per product.accountAmount
The amount you received for the product as a line-item per product.jvPayout (seller only)
The total amount of JV payouts for this product as a line-item per product.affiliatePayout (seller only)
The amount affiliate received for the product as a line-item per product.taxAmount
The product tax amount the customer paid as a line-item per product.shippingAmount
The product shipping amount the customer paid as a line-item per productshippingLiable
Whether your account is credited for shipping and handling as a line-item per product
Format Updates:
All monetary values in USD
Encoded in UTF-8
Time of transaction in ISO 8601.
Because we’re using ISO 8601 Basic Notation, there aren’t any date/time delimiters. This is different from former versions of INS which used RFC-339.
Example: 20200819T144359-0700 would be August 29, 2020 at 14:43:59-07:00.
See the Legacy Versions section for information about the parameters used by older versions. Some older versions of Instant Notification do not encrypt the notification, so we do not recommend their use.
Notification Example
This is a sample of the unencrypted JSON notification showing the structure of the key-value pairs for Version 7.0 of Instant Notification.
{
"transactionTime": "2016-06-05T13:47:51-06:00",
"receipt": "CWOGBZLN",
"transactionType": "SALE",
"vendor": "testacct",
"affiliate": "affiliate1",
"role": "VENDOR",
"totalAccountAmount": 0.00,
"paymentMethod": "VISA",
"totalOrderAmount": 0.00,
"totalTaxAmount": 0.00,
"totalShippingAmount": 0.00,
"currency": "USD",
"orderLanguage": "EN",
"trackingCodes": [
"tracking_code"
],
"lineItems": [
{
"itemNo": "1",
"productTitle": "Product Title",
"shippable": false,
"recurring": false,
"accountAmount": 5.00,
"quantity": 1,
"downloadUrl": "<download_url>"
"lineItemType": "CART"
}
{
"itemNo": "2",
"productTitle": "Second Product",
"shippable": false,
"recurring": true,
"accountAmount": 2.99,
"quantity": 1,
"downloadUrl": "<download_url>"
"lineItemType": "CART"
}
],
"customer": {
"shipping": {
"firstName": "TEST",
"lastName": "GUY",
"fullName": "Test Guy",
"phoneNumber": "",
"email": "[email protected]",
"address": {
"address1": "12 Test Lane",
"address2": "Suite 100",
"city": "LAS VEGAS",
"county": "LAS VEGAS",
"state": "NV",
"postalCode": "89101",
"country": "US"
}
},
"billing": {
"firstName": "TEST",
"lastName": "GUY",
"fullName": "Test Guy",
"phoneNumber": "",
"email": "[email protected]",
"address": {
"state": "NV",
"postalCode": "89101",
"country": "US"
}
}
},
"upsell": {
"upsellOriginalReceipt": "XXXXXXXX",
"upsellFlowId": 55,
"upsellSession": "VVVVVVVVVV",
"upsellPath": "upsell_path"
},
"hopfeed": {
"hopfeedClickId": "hopfeed_click",
"hopfeedApplicationId": 0000,
"hopfeedCreativeId": 0000,
"hopfeedApplicationPayout": 0.00,
"hopfeedVendorPayout": 0.00
},
"version": 6.0,
"attemptCount": 1,
"vendorVariables": {
"v1": "variable1",
"v2": "variable2"
}
}Legacy Code Samples
Java
The following Java code will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key.
Note: This requires the jakarta commons codec library to be functional.
public static boolean ipnValid(HttpServletRequest request) {
String secretKey = "YOUR SECRET KEY";
List ipnFields = new ArrayList();
@SuppressWarnings("rawtypes")
Enumeration params = request.getParameterNames();
while (params.hasMoreElements()) {
String param = (String) params.nextElement();
// cverify is computed by all POST parameters so any get parameters
// on the notification url should be skipped as well.
if (param.equals("cverify")) {
continue;
}
ipnFields.add(param);
}
Collections.sort(ipnFields);
StringBuilder pop = new StringBuilder();
for (String field : ipnFields) {
pop.append(request.getParameter(field));
pop.append("|");
}
pop.append(secretKey);
String expectedCVerify = DigestUtils.shaHex(pop.toString().getBytes("UTF-8")).substring(0, 8);
return expectedCVerify.equalsIgnoreCase(request.getParameter("cverify"));
}PHP
The following PHP will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key (e.g. not URL-encoded).
Response Types:
1 = Pass
0 = Fail
<?php
function ipnVerification() {
$secretKey="YOUR SECRET KEY";
$pop = "";
$ipnFields = array();
foreach ($_POST as $key => $value) {
if ($key == "cverify") {
continue;
}
$ipnFields[] = $key;
}
sort($ipnFields);
foreach ($ipnFields as $field) {
// if Magic Quotes are enabled $_POST[$field] will need to be
// un-escaped before being appended to $pop
$pop = $pop . $_POST[$field] . "|";
}
$pop = $pop . $secretKey;
$calcedVerify = sha1(mb_convert_encoding($pop, "UTF-8"));
$calcedVerify = strtoupper(substr($calcedVerify,0,8));
return $calcedVerify == $_POST["cverify"];
}
?>
C#
The following C# will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key (e.g. not URL-encoded).
///
/// This method takes the same named post parameters that are sent in the ClickBank Instant Notification Service.
/// True if the ClickBank passed paramter cverify matches the calculated sha1 of the provided data, False otherwise
///
public static bool ipnValid(HttpRequest request)
{
string secretKey = "YOUR SECRET KEY";
List ipnFields = new List();
foreach(string param in request.Form.Keys) {
if (param.Equals("cverify")) {
continue;
}
ipnFields.Add(param);
}
ipnFields.Sort();
string pop = "";
foreach(String field in ipnFields) {
pop += request.Form.Get(field) + "|";
}
pop += secretKey;
string cverify = request.Form.Get("cverify");
byte[] hashedData = new SHA1Managed().ComputeHash(Encoding.UTF8.GetBytes(pop));
string calced_verification = BitConverter.ToString(hashedData).Replace("-", "").ToUpper().Substring(0, 8);
return calced_verification.Equals(cverify);
}
Python
The following Python will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key (e.g. not URL-encoded).
#!/usr/bin/env python -tt
import hashlib
##
# Verify cverify from an ipn.
# @param post_params: A dictionary of all POST parameters from the notification
# @return: True if the cverify parameter is valid, false otherwise
def ipnVerification(post_params):
secret_key = "YOUR SECRET KEY"
pop = ""
ipn_fields = []
for key in post_params.keys():
if key == "cverify":
continue
ipn_fields.append(key)
ipn_fields.sort()
for field in ipn_fields:
pop += post_params[field] + "|"
pop += secret_key
return post_params["cverify"] == hashlib.sha1(pop).hexdigest()[:8].upper()
Ruby
The following Ruby will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key (e.g. not URL-encoded).
#!/usr/bin/env ruby
require 'digest/sha1'
# Verify cverify from an ipn. post_params is a Hash of all
# POST parameters from the ipn.
def ipnVerification(post_params)
secret_key = "YOUR SECRET KEY"
pop = ""
ipn_fields = []
post_params.each_key do |key|
if key == "cverify"
next
end
ipn_fields << key
end
ipn_fields.sort
ipn_fields.each do |field|
pop += post_params[field] + "|"
end
pop += secret_key
calced_verification = Digest::SHA1.hexdigest(pop).upcase[0,8]
return calced_verification == post_params["cverify"]
end
VB.net
The following VB.net will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key (e.g. not URL-encoded).
public Function ipnVerification(request as HttpRequest)
Dim secretKey as String = "YOUR SECRET KEY"
Dim ipnFields as New List()
Dim sha As New SHA1CryptoServiceProvider()
For Each param In request.Form.Keys()
if param.Equals("cverify") then Continue For
ipnFields.Add(param)
Next
ipnFields.Sort()
Dim pop as String = ""
For Each field in ipnFields
pop += request.Form.Get(field) + "|"
Next
pop += secretKey
Dim result() As Byte = sha.ComputeHash(New System.Text.ASCIIEncoding().GetBytes(pop))
Dim calced_verification As String = BitConverter.ToString(result).Replace("-",
"").ToUpper().Substring(0, 8)
Return calced_verification.Equals(cverify)
End Function
Additional Resources & Related Articles
KNOWLEDGE BASE: Cart Abandonment
KNOWLEDGE BASE: ClickBank APIs