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:

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.

Getting Started

Understanding Instant Notification

Prior to implementing this feature, you should familiarize yourself with the following information.

Post Parameters: Instant Notification Version 2.1

The following post parameters are passed from the ClickBank Instant Notification service version 2.1 (the most up-to-date version).

When a parameter contains no value, the Instant Notification string will contain the parameter tag without a value. It is also possible for the Instant Notification service to deliver more than one POST on a single receipt. For more information, please review the FAQ Section of this document.

Post Parameters: Instant Notification Version 1

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 2 as soon as possible, as Version 1 will eventually be removed.

Transaction Types

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.

Payment Methods

There 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 Account 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 Account 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 Account 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 Nofification 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 ipnFields:
        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 << 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

No related posts.