ClickBank Knowledge Base /General Account Help/Tools & Features

Instant Notification Service

Melissa
posted this on December 26, 2012, 13:14

Update - December 2014

In the coming months, ClickBank will be deprecating older versions of Instant Notification in preparation of the new multi-line item transaction system that will be capable of supporting shopping carts.  This necessitates a full migration of all clients to Version 6.0 of the Instant Notification Service. Version 6.0 provides responses in JSON format and additional parameters as discussed below.

Overview

ClickBank offers an Instant Notification service that notifies you of transactions within the ClickBank system for your account. It sends data in a near real-time fashion for the following action types:

  • Sale
  • Rebill
  • Refund
  • Chargeback
  • Cancel Rebill
  • Test

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. To prevent fraud, one of the parameters, the cverify field, is used to verify the validity of the other fields.

Note: This service is intended for use by experienced programmers. Clients without extensive programming skills should refrain from implementing Instant Notifications without first enlisting the services of an experienced programmer.

How it Works

The ClickBank 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:

  1. An action occurs in the ClickBank system (ex sale, rebill, refund, etc)
  2. ClickBank posts FORM parameters to a URL you specify
  3. ClickBank observes the server response
  4. A program you build processes the variables

Setting up the service on your ClickBank account is straightforward. However, it is also necessary to build a program that processes the Instant Notification URL Parameters, which is a more technical task. In order to make good use of this service, your program must at least process the parameters outline in the URL Parameters section of this document.

What You Need to Know

For the Instant Notification service to function properly, you need to understand the following items. Failure to properly understand and implement these items will result in removal of Instant Notification from your account.

  1. What a HTML FORM POST to a URL is
  2. What Post Parameters are
  3. What a Secret Key is
  4. How to implement Cipher
  5. The importance of utilizing Secure Socket Layer (SSL)
  6. The effects of Response Code Monitoring

If you don't understand one or more of the above items, we recommend that you enlist the services of a professional who understands these implementation items. Failure to do so could result in removal of this feature from your account. 

 

Understanding the Changes Made to Verification With Version 6

For version 6 of instant notifications, ClickBank changed the way verifications are generated in order to make it more secure by encrypting the important data in the notification.  The format of the notification has also been changed to make use of the JSON format, which makes it easier to consume and use. 

The new base structure is sent out as follows:

{"notification": "<ENCRYPTED_NOTIFICATION>", "iv": "<INITIALIZATION_VECTOR>"}

Encrypted Notification

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.  Several examples of how to decrypt the notification are listed below, 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 used in parallel with your ClickBank secret key to decrypt the notification.

The Unencrypted Notification

This is a sample of the unencrypted JSON notification showing the structure of the key-value pairs for Version 6.0 of Instant Notification. 

NOTE: The JSON format does not actually support inline comments as shown below.  They are only inlined to help developers understand the data and the actual notification will be sent without the comments.

 {
    // Time of the transaction in RFC-3339 format [25 characters]
    "transactionTime": "2014-09-05T13:47:51-06:00",
    // ClickBank receipt [8 - 21 characters]
    "receipt": "CWOGBZLN",
    // Type of Transaction (SALE, JV_SALE, INSF, RFND, CGBK, BILL, JV_BILL,
    // TEST_SALE, TEST_JV_SALE, TEST_BILL, TEST_JV_BILL, TEST_RFND)
    "transactionType": "SALE",
    // Vendor nickname [5 - 10 characters]
    "vendor": "testacct",
    // Affiliate nickname [5 - 10 characters]
    "affiliate": "bobkelso",
    // Your role in the transaction (e.g., VENDOR, AFFILIATE, JV_VENDOR) [6 - 9 characters]
    "role": "VENDOR",
    // Total you received for this transaction in USD [numeric value with 2 decimal precision]
    "totalAccountAmount": 0.00,
    // Payment method used by the customer. [AMEX, AUST, BLME, DISC, DNRS, ELV, ENRT, IMAS,
    // JCBC, MAES, MSTR, PYPL, STVA, SWIT, TEST, VISA]
    "paymentMethod": "VISA",
    // Total the customer was charged [numeric value with 2 decimal precision]
    "totalOrderAmount": 0.00,
    // Total the customer paid in taxes. ONLY AVAILABLE TO THE VENDOR [numeric value with 2
    // decimal precision]
    "totalTaxAmount": 0.00,
    // Total the customer paid in shipping. ONLY AVAILABLE TO THE VENDOR [numeric value with
    // 2 decimal precision]
    "totalShippingAmount": 0.00,
    // The currency the customer paid in. ONLY AVAILABLE TO THE VENDOR [3 characters]
    "currency": "USD",
    // The language displayed on the order form. ONLY AVAILABLE TO THE VENDOR
    // [DE, EN, ES, FR, IT, PT]
    "orderLanguage": "EN",
    // Any tracking codes passed into the order from. ONLY AVAILABLE TO THE VENDOR AND
    // THE AFFILIATE [0 - 24 characters each]
    "trackingCodes": [
        "tracking_code"
    ],
    // A list of products purchased on this order
    "lineItems": [
        {
            // Product SKU. [1 - 10 characters]
            "itemNo": "1",
            // Product title. [0 - 255 characters]
           "productTitle": "Product Title",
            // Was the product shippable? [true, false]
            "shippable": true,
           // Was the product subscription based? [true, false]
            "recurring": true,
            // Amount you received on this given line item. [numeric value with 2
            // decimal precision]
            "accountAmount": 0.00,
            // Product download URL for the customer. ONLY AVAILABLE TO THE VENDOR
            "downloadUrl": "<download_url>"
        }
    ],
    "customer": {
        // Shipping customer information. ALL FIELDS ARE ONLY AVAILABLE TO THE VENDOR
        // [each field is 0 - 255 characters]
        "shipping": {
            "firstName": "TEST",
            "lastName": "GUY",
            "fullName": "Test Guy",
           "phoneNumber": "",
            "email": "test@example.net",
            "address": {
                "address1": "12 Test Lane",
                "address2": "Suite 100",
                "city": "LAS VEGAS",
                "county": "LAS VEGAS",
                "state": "NV",
                "postalCode": "89101",
                "country": "US"
            }
        },
        // Billing customer information. FIELDS ARE ONLY AVAILABLE TO THE VENDOR UNLESS
        // OTHERWISE STATED [all fields are 0 - 255 characters]
        "billing": {
            "firstName": "TEST",
            "lastName": "GUY",
            "fullName": "Test Guy",
            "phoneNumber": "",
            "email": "test@example.net",
            "address": {
                // AVAILABLE TO ALL RECIPIENTS
                "state": "NV",
                // AVAILABLE TO ALL RECIPIENTS
                "postalCode": "89101",
                // AVAILABLE TO ALL RECIPIENTS
                "country": "US"
            }
        }
    },
    // If the order is part of an upsell, that information will be found here
    "upsell": {
        // ClickBank receipt number that started the upsell flow
        "upsellOriginalReceipt": "XXXXXXXX",
        // ID of the upsell flow. ONLY AVAILABLE TO THE VENDOR [integer value]
        "upsellFlowId": 55,
        // Session ID for the upsell. ONLY AVAILABLE TO THE VENDOR [0 - 16 characters]
        "upsellSession": "VVVVVVVVVV",
        // Upsell path. ONLY AVAILABLE TO THE VENDOR [0 - 12 characters]
        "upsellPath": "upsell_path"
    },
    // If there is Pytch information associated with this order, the information will be
    // found here and is available to all recipients.
    "hopfeed": {
        "hopfeedClickId": "hopfeed_click",
        "hopfeedApplicationId": 0000,
        "hopfeedCreativeId": 0000,
        "hopfeedApplicationPayout": 0.00,
        "hopfeedVendorPayout": 0.00
    },
    // Version of the instant notification. [double numeric value]
    "version": 6.0,
    // The number of attempts ClickBank has tried to send this instant notification
    // before receiving a success, or failing with too many attempts. [integer value]
    "attemptCount": 1,

   // Any vendor provided variables to the paylink will be provided here.   
    "vendorVariables": {
       "v1": "variable1", 
       "v2": "variable2" 
    }

}

Code Examples on Decrypting the Notification

Java:

 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:

 <?php
// NOTE: the mcrypt libraries need to be installed and listed as an available extension in
// your phpinfo() to be able to use this method of decryption.

$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(mcrypt_decrypt(MCRYPT_RIJNDAEL_128,

                                 substr(sha1($secretKey), 0, 32),

                                 base64_decode($encrypted),

                                 MCRYPT_MODE_CBC,

                                 base64_decode($iv)), "\0..\32");

error_log("Decrypted: $decrypted");

// convert the decrypted string to a JSON object...
$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:

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:

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

 

- Version 1: *** This version will be deprecated in Q3 2014. Please use Version 6.0 (see above)

The following post parameters are used in Instant Notification Version 1. Please note that Version 1 is missing many new parameters. We recommend upgrading to Version 4 as soon as possible, as Version 1 will eventually be removed.

Parameter

Description

Details

caffitid

affiliate TID [only populated for affiliate]

0 – 24 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 item sku

1 – 10 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, ELV, ENRT, IMAS, JCBC, 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 vendor 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  *** This version will be deprecated in Q3 2014. Please use Version 6.0 (see above)

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 item sku

1 – 10 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 – 24 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, ELV, ENRT, IMAS, JCBC, 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 *** This version will be deprecated in Q3 2014. Please use Version 6.0 (see above)

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

 

Transaction Types* See "Transaction Types" ** See "Cipher" § Present when a parent receipt exists for the transaction

There are a number of values you can receive in the ctransaction parameter. These values are listed below with a brief description of their purpose.

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" action.
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.
TEST Triggered by using the test link on the site page.

Payment MethodsThere are a number of values you can receive in the "ctranspaymentmethod" parameter. These values are listed below.

  • PYPL
  • VISA
  • MSTR
  • DISC
  • AMEX
  • SWIT
  • SOLO
  • JCBC
  • DNRS
  • ENRT
  • AUST
  • BLME
  • STVA
  • MAES

Secure Socket Layer (SSL)

It is strongly recommended that you utilize this feature with Secure Socket Layer (SSL) enabled. Using this feature without Secure Socket Layer (SSL) enabled can expose your sales data to Internet thieves. However, because credit card and bank information is not transmitted via the Instant Notification service, ClickBank does not require Secure Socket Layer (SSL) to encrypt Instant Notification transmissions. 

Response Code Monitoring (Retry Logic)

The Instant Notification service attempts to POST information via HTML to the URL specified on your My Site page. If our attempt to post receives a response code from your system of something other than 200, ClickBank will retry delivering the data an hour later. The service will continue retrying once an hour for up to 72 hours, after which the feature will no longer attempt delivery. 

Cipher (Preventing Fraud)

Cipher (pronounced SAI-fuhr) 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 (see URL Parameters). 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 Code Samples for examples.

Implementation

After gaining a sound understanding of the previous section of this document, we recommend that you test the feature before implementing. After completing a successful test, you can set up your account for the Instant Notification service.

Request Access

Request access to the Instant Notification service by following these steps:

  1. Log in to your account
  2. Click the Settings tab
  3. Click My Site in the sub nav
  4. Locate the Instant Notification field and click the Click HERE to request access hyperlink
  5. Fill out the form and thoroughly review the terms of use.
  6. Click the Submit button at the bottom of the form

Test Connectivity and Processing

Test the connectivity and successful processing of the URL parameters between ClickBank and your server by following these steps:

    1. Log in to your account
    2. Click the Settings tab
    3. Click My Site in the sub nav
    4. Enter the URL you want ClickBank to send the notifications to in the Instant Notification 1 field Note: Do not click Save Changes
    5. Click Test to the right of the URL
    6. Review the response in the popup window to identify if the test was a success

If the test was not successful, remove the URL from the Instant Notification field and troubleshoot possible problems with connectivity or your programming.

Important:You should not populate the Instant Notification field unless you can conduct a successful test. Doing so may result in your access to the feature being disabled.

A sample notification will be sent with a receipt of ******** and a transaction type of TEST.

Account Setup

Now that you have been granted access to the feature and have conducted a successful test, it's time to complete the account setup of the Instant Notification service. Setting up the service is straightforward and involves the following steps.

  1. Log into your account
  2. Click the Settings tab
  3. Click My Site in the sub nav
  4. Enter a Secret Key on your My Site page
  5. Enter an Instant Notification URL in the Instant Notification 1 field (ports 80 or 443 - SSL Recommended)
  6. Click Test to the right of the URL before you save the changes
  7. Review the response in the popup window to identify if the test was a success
  8. Click Save Changes

Once the setup is complete, the Instant Notification transmissions will begin immediately.

Disabling

Removing the URL from the Instant Notification field on the My Site page will stop the system from delivering notifications. 

FAQ

Q: I'm not an experienced programmer. Should I attempt to implement ClickBank Instant Notifications?
A: No. There are several aspects of the Instant Notification service that require programming experience.

Q: Is it possible for the Instant Notification service to deliver more than one POST on a single receipt?
A: Yes. There are many scenarios where this is true. For instance, you will receive multiple POSTs for a single transaction if a refund is given and then reversed. This would result in delivery of a RFND action POST and then a SALE action post. The first action is a result of the original sale being refunded. The second action is a result of the sale being reinstated.

Q: How do I stop the ClickBank Instant Notification service from making POSTs to me?
A: Removing the Instant Notification URL from your My Site page will stop the system from delivering the notifications.

Q: Will I always receive all the Parameters or only when they contain values?
A: You will always receive all the parameters. When a parameter contains no value, the Instant Notification string will contain the parameter tag without a value.

Q: Why do some of the Parameters have a 0 in the number of characters to expect?
A: These Parameters may not contain any value during the post, which is why they are listed with the possibility for 0 characters.

Q: Am I required to use SSL with the ClickBank Instant Notification service?
A: It is not required, but is highly recommended as it provides you with protection against Internet thieves.

Q: Am I required to use Cipher with the ClickBank Instant Notification service?
A: It is required. You must add a secret key to your account to enable Instant Notifications.

Q: Are the code samples provided by ClickBank fully functional and ready to go?
A: No. In most cases, the code samples must be nested in a program. If this is not understood, we recommend that you enlist the services of a professional programmer.

Q: Will ClickBank Instant Notification work with a self-signed SSL certificate?
A: No. A valid certificate is required.

Q: Is it possible to test the Instant Notification service prior to implementing?
A: Yes. Test connectivity and processing between ClickBank and your server by following these steps:

  1. Enter the URL you want ClickBank to send the notification to
  2. Click Test to the right of the URL before you save the changes
  3. Review the response in the popup window to identify if the test was a success

Q: Can I send to notifications to more than one URL?
A: Yes. A second notification URL can be added after saving your first notification URL. Note: all the same rules apply to the second notification URL. 

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.

JAVA

Cipher (Validation Processing Code)

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.

Code Sample

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

Cipher (Validation Processing Code)

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

Code Sample

<?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#

Cipher (Validation Processing Code)

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

Cipher (Validation Processing Code)

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

Cipher (Validation Processing Code)

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 &lt;&lt; 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

Cipher (Validation Processing Code)

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

 

 
Topic is closed for comments