2Checkout Documentation

Notifications

You can use the Instant Notification Service (INS) to automate order management processes by accepting order information via web posts. The INS is a service which will post sets of parameters to any URL you specify. Each post represents a message containing all the information you need about a specific event (such as when a recurring order re-bills successfully).

Enabling Notifications

In the seller admin, you can enable INS notifications under the Notifications tab. Messages can be enabled or disabled by selecting the checkbox for each message type and you may define either a Global URL for receipt of all messages or individual URLs per message as needed. You may also view and resend Successful and Failed INS notifications by clicking the Success and Failed sub-tab on the Notifications page. By clicking the Test sub-tab you may send test INS posts from inside your account to your URL’s.

Please Note: INS notifications are not sent on demo sales so you should use either a live sale or a sandbox account to test your INS script.

Listening for Notifications

Notifications are sent by an HTTP POST request to the message URL that you specified on the Notifications tab. The message parameters are passed as key => value pairs. Your message URL should route to the script where you will be handling the message. You can listen for messages by simply setting up logic in your application to take action based on the message_type parameter that is passed in each message.

Validating the Notification

Each notification message will include an MD5 hash that is computed using the secret word that you set up under the Site Management page in the seller area.

The hash is returned on each message through the md5_hash key and is computed as follows:

UPPERCASE(MD5_ENCRYPTED(sale_id + vendor_id + invoice_id + Secret Word))

Each of our community supported libraries provides a binding to validate the hash on a notification message.

Example

Below is an example PHP script that listens for the Fraud Status Changed message.

<?php

    if ($_POST['message_type'] == 'FRAUD_STATUS_CHANGED') {

        $insMessage = array();
        foreach ($_POST as $k => $v) {
        $insMessage[$k] = $v;
        }

        # Validate the Hash
        $hashSecretWord = "tango"; # Input your secret word
        $hashSid = 1303908; #Input your seller ID (2Checkout account number)
        $hashOrder = $insMessage['sale_id'];
        $hashInvoice = $insMessage['invoice_id'];
        $StringToHash = strtoupper(md5($hashOrder . $hashSid . $hashInvoice . $hashSecretWord));

        if ($StringToHash != $insMessage['md5_hash']) {
            die('Hash Incorrect');
        }

        switch ($insMessage['fraud_status']) {
            case 'pass':
                # Do something when sale passes fraud review.
                break;
            case 'fail':
                # Do something when sale fails fraud review.
                break;
            case 'wait':
                # Do something when sale requires additional fraud review.
                break;
        }
    }

?>