2008-02-19 Release Summary

1. Instant Notification Summary

1.1 OVERVIEW

ClickBank is offering an Instant Notification service for backend integration. The Instant Notification service notifies you of transactions within the ClickBank system for your account. The feature 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.

Ultimately, this feature will allow you to easily integrate your back-end operations with the ClickBank transaction management system.

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.

1.2 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 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 Section 2.1.1 of this document.

To best explain how to use this feature first the "rules" outlining its use are defined, and then step-by-step getting started instructions are provided to outline its implementation. Lastly, code samples are available.

1.3 IMPLEMENTATION RULES

The following rules must be upheld in order for the Instant Notification services to function properly. Failure to adhere to the following rules will result in removal of the feature from your account.

  1. Client understands what a HTML FORM POST to a URL is
  2. Client understands what URL Parameters are
  3. Client understands what a Secret Key is
  4. Client understands how to implement Cipher
  5. Client understands the importance of utilizing Secure Socket Layer (SSL)
  6. Client understands the affects of Response Code Monitoring

If for any reason the information listed above is not understood, we recommend that you enlist the services of professional who understands the implementation rules. Failure to do so could result in removal of this feature from your account.

2 GETTING STARTED

2.1 UNDERSTANDING THE FEATURE

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

2.1.1 URL PARAMETERS

The following URL parameters are passed from the ClickBank Instant Notification service.

Parameter Description Detail
ccustname customer name 1-510 Characters
ccuststate customer state 0-2 Characters
ccustcc customer country code 0-2 Characters
ccustemail customer email 1-255 Characters
cproditem ClickBank product number 1-5 Characters
cprodtitle title of product at time of purchase 0-255 Characters
cprodtype type of product on transaction (STANDARD, and RECURRING) 8-11 Characters
ctransaction * action taken 4-15 Characters
ctransaffiliate affiliate on transaction 0-10 Characters
ctransamount amount paid to party receiving notification (in pennies (1000 = $10.00)) 3-10 Characters
ctranspaymentmethod method of payment by customer 0-4 Characters
ctranspublisher vendor on transaction 5-10 Characters
ctransreceipt ClickBank receipt number 8-13 Characters
caffitid affiliate tracking id 0 - 24 Characters
cvendthru extra information passed to order form with duplicated information removed 0-1024 Characters
cverify ** the "cverify" parameter is used to verify the validity of the previous fields 8 Characters
ctranstime ** the Epoch time the transaction occurred (not included in cverify) 10 Characters
* See Section 2.1.1.1
** See Section 2.1.4

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.

2.1.1.1 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.

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.

2.1.2 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.

2.1.3 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.

2.1.4 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 Section 2.1.1). 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.

Note: ctranstime parameter is not included in the encryption algorithm for the 'cverify' parameter.

Please see Section 4 for code samples.

2.2 IMPLEMENTATION

After gaining a sound understanding of Section 2.1 in this document, we recommend that you test the feature before implementing. After completing a successful test, you will setup your account for the Instant Notification service.

2.2.1 REQUEST ACCESS

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

  1. Log into 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" hyper link
  5. Fill out the form and thoroughly review the terms of use.
  6. Click the "Submit" button at the bottom of the form

2.2.2 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 into 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

    5. Note: Do not "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 trouble shoot 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.

The following Instant Notification parameters and values are passed for each execution of the test.

Parameter Value
ccustname Test User
ccuststate
ccustcc
ccustemail testuser@somesite.com
cproditem 399
cprodtitle A passed in title
cprodtype STANDARD
ctransaction TEST
ctransaffiliate
ctransamount 100
ctranspaymentmethod VISA
ctranspublisher "Real Vendor Nickname"
ctransreceipt XXXXXXXX
caffitid
cvendthru
cverify "Real cverify"

2.2.3 ACCOUNT SETUP

Now that you have been granted access to the feature and have conducted a successful test, its 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.

2.2.4 DISABLING

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

3 FAQ CONTENT

  1. I'm not an experienced programmer, should I attempt to implement ClickBank Instant Notifications?

    No. There are several aspects of the Instant Notification service that require programming experience.

  2. Is possible for the Instant Notification service to deliver more than one POST on a single receipt?

    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.

  3. How do I stop the ClickBank Instant Notification service from making POSTs to me?

    Removing the Instant Notification URL from your "My Site" page will stop the system from delivering the notifications.

  4. Will I always receive all the Parameters or only when they contain values?

    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

  5. Why do some of the Parameters have a "0" in the number of characters to expect?

    These Parameters may not contain any value during the post, which is why they are listed with the possibility for "0" characters.

  6. Is it required that I use SSL with the ClickBank Instant Notification service?

    It is not required, but is highly recommended as it provides protection against internet thieves.

  7. Is it required that I use Cipher with the ClickBank Instant Notification service?

    It is required. You must add a secret key to your account to enable Instant Notifications.
  8. Are the code samples provided by ClickBank fully functional and ready to go?

    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.

  9. Will ClickBank Instant Notification work with self-signed SSL certificate?

    No. A valid certificate is required.

  10. Is it possible to test the Instant Notification service prior to implementing?

    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

  11. Can I send to notifications to more than one URL?

    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.

4 CODE SAMPLE(S)

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 and are outside the scope of this guide.

4.1 JAVA

4.1.1 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 (http://commons.apache.org/codec/) to be functional.

4.1.1.1 CODE SAMPLE

    public boolean validateApiNotification(HttpServletRequest request) {
        String xxpop = "";
        String cverify = request.getParameter("cverify");
        
         String pop = String.format("%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s",
            request.getParameter("ccustname"),
            request.getParameter("ccustemail"),
            request.getParameter("ccustcc"),
            request.getParameter("ccuststate"),
            request.getParameter("ctransreceipt"),
            request.getParameter("cproditem"),
            request.getParameter("ctransaction"),
            request.getParameter("ctransaffiliate"),
            request.getParameter("ctranspublisher"),
            request.getParameter("cprodtype"),
            request.getParameter("cprodtitle"),
            request.getParameter("ctranspaymentmethod"),
            request.getParameter("ctransamount"),
            request.getParameter("caffitid"),
            request.getParameter("cvendthru"),
            "YOUR SECRET KEY");

        try {
            MessageDigest digest = MessageDigest.getInstance("SHA");
            byte[] b = digest.digest(pop.getBytes());

            xxpop = new String(Hex.encodeHex(b)).toUpperCase();
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        }

        return xxpop.equalsIgnoreCase(cverify);
    }

4.2 PHP

4.2.1 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

4.2.1.1 CODE SAMPLE

<?php
 
function cbValid() {

	$key='YOUR SECRET KEY';
	$ccustname = $_REQUEST['ccustname'];
	$ccustemail = $_REQUEST['ccustemail'];
	$ccustcc = $_REQUEST['ccustcc'];
	$ccuststate = $_REQUEST['ccuststate'];
	$ctransreceipt = $_REQUEST['ctransreceipt'];
	$cproditem = $_REQUEST['cproditem'];
	$ctransaction = $_REQUEST['ctransaction'];
	$ctransaffiliate = $_REQUEST['ctransaffiliate'];
	$ctranspublisher = $_REQUEST['ctranspublisher'];
	$cprodtype = $_REQUEST['cprodtype'];
	$cprodtitle = $_REQUEST['cprodtitle'];
	$ctranspaymentmethod = $_REQUEST['ctranspaymentmethod'];
	$ctransamount = $_REQUEST['ctransamount'];
	$caffitid = $_REQUEST['caffitid'];
	$cvendthru = $_REQUEST['cvendthru'];
	$cbpop = $_REQUEST['cverify'];

	$xxpop = sha1("$ccustname|$ccustemail|$ccustcc|$ccuststate|$ctransreceipt|$cproditem|$ctransaction|"
		."$ctransaffiliate|$ctranspublisher|$cprodtype|$cprodtitle|$ctranspaymentmethod|$ctransamount|$caffitid|$cvendthru|$key");

    $xxpop=strtoupper(substr($xxpop,0,8));

    if ($cbpop==$xxpop) return 1;
	else return 0;
}
?>