Skip to main content

Notifications

Overview

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 that 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 URLs.

ins 2checkout

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 in your account.

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;
        }
    }

?>

 

Delete Coupon

Overview

The delete_coupon call is used to delete a coupon.

URL: https://www.2checkout.com/api/products/delete_coupon

HTTP Method: POST

Input Parameters

Parameter Description
coupon_code String value of coupon code for deleting coupon. Required.

Data Returned

Parameter Description
response_code Tells the user whether or not the operation was successful.
response_message Tells the user why the operation was or was not successful.

Example API Call

curl -G https://www.2checkout.com/api/products/detail_coupon \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'coupon_code=APITEST002'

Example Successful Response

 {
       "response_code" : "OK",
       "response_message" : "Coupon successfully deleted."
    }

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to coupon.

List Payments

Overview

The list_payments call is used to get a list of past payments.

URL: https://www.2checkout.com/api/acct/list_payments

HTTP Method: GET

Input Parameters

No input parameters required.


Data Returned

Parameter Description
payment_id Identifier of payment
payment_identifier Identifier of payment batch
date_paid Date of payment (YYYY-MM-DD MM:HH:SS format)
amount Amount of payment
reserve_held Reserve held
total_reserve_released Reserve released
date_reserve_released Date reserve released
payment_type Method of money transfer
total_sales Total amount of sales included in payment
total_fees Total amount of fees included in payment
total_refunds Total amount of refunds included in payment
total_chargeback_fees Total amount of chargebacks included in payment
total_adjustments Total amount of adjustments included in payment
total_commissions Total amount of commissions earned included in payment
total_outgoing_commissions Total amount of commissions paid included in payment
total_balance_forward Total amount of forwarded balance included in payment
void Wheter or not the payment was voided. (0=not voided, 1=voided)
date_voided Date the payment was voided.

Example API calls using cURL

curl -G https://www.2checkout.com/api/acct/list_payments \
    -H 'Accept: application/json' -u 'username:password'

Example Successful Response

{
       "payments" : [
          {
             "amount" : "50240.51",
             "date_paid" : null,
             "date_reserve_released" : null,
             "date_voided" : null,
             "payment_id" : "4681565342",
             "payment_identifier" : "wire_999042012",
             "payment_type" : "wire",
             "reserve_held" : "1646.07",
             "total_adjustments" : "0.00",
             "total_balance_forward" : "0.00",
             "total_chargeback_fees" : "0.00",
             "total_commissions" : "0.00",
             "total_fees" : "1941.34",
             "total_outgoing_commissions" : "0.00",
             "total_refunds" : "2418.46",
             "total_reserve_released" : "1397.38",
             "total_sales" : "54869.00",
             "void" : null
          },
          {
             "amount" : "45616.52",
             "date_paid" : null,
             "date_reserve_released" : null,
             "date_voided" : null,
             "payment_id" : "4676285423",
             "payment_identifier" : "wire_992042012",
             "payment_type" : "wire",
             "reserve_held" : "1499.83",
             "total_adjustments" : "0.00",
             "total_balance_forward" : "0.00",
             "total_chargeback_fees" : "0.00",
             "total_commissions" : "0.00",
             "total_fees" : "1768.57",
             "total_outgoing_commissions" : "0.00",
             "total_refunds" : "2553.00",
             "total_reserve_released" : "1463.62",
             "total_sales" : "49994.30",
             "void" : null
          }
       ],
       "response_code" : "OK",
       "response_message" : "payment info retrieved"
    }

 

Detail Pending Payment

Overview

The detail_pending_payment call is used to get a detailed estimate of the current pending payment.

URL: https://www.2checkout.com/api/acct/detail_pending_payment

HTTP Method: GET

Input Parameters

No input parameters required.

Data Returned

Parameter Description
amount Amount of payment
reserve_held Reserve held
total_sales Total amount of sales included in payment
total_fees Total amount of fees included in payment
total_refunds Total amount of refunds included in payment
total_chargeback_fees Total amount of chargebacks included in payment
total_adjustments Total amount of adjustments included in payment
total_commissions Total amount of commissions earned included in payment
total_outgoing_commissions Total amount of commissions paid included in payment
total_balance_forward Total amount of forwarded balance included in payment
payment_fee Amount charged for sending payment
payment_id Identifier of payment
payment_method Method of money transfer
release_level Release level

Example API calls using cURL

curl -G https://www.2checkout.com/api/acct/detail_pending_payment \
    -H 'Accept: application/json' -u 'username:password'

Example Successful Response

 {
       "payment" : {
          "amount" : "999.99",
          "payment_fee" : "0.00",
          "payment_id" : "2436561667",
          "payment_method" : "ach",
          "release_level" : "15",
          "reserve_held" : "14.19",
          "total_adjustments" : "61.07",
          "total_balance_forward" : "0.00",
          "total_chargeback_fees" : "0.00",
          "total_commissions" : "0.21",
          "total_fees" : "86.92",
          "total_outgoing_commissions" : "4.35",
          "total_refunds" : "275.36",
          "total_reserve_released" : "0.00",
          "total_sales" : "283.86"
       },
       "response_code" : "OK",
       "response_message" : "payment info retrieved"
    }

 

Detail Coupon

Overview

The detail_coupon call is used to retrieve the details for a single coupon.

URL: https://www.2checkout.com/api/products/detail_coupon

HTTP Method: GET


Input Parameters

Parameter Description
coupon_code The string value of coupon code. Required

Data Returned

Parameter Description
coupon_code String value of coupon code.
date_expire Expiration Date. (YYYY-MM-DD)
percentage_off Percentage Discount
type Coupon type
value_off Fixed Discount
minimum_purchase Minimum purchase amount.
product_id ID of product selected for coupon.

Example API Call

curl -G https://www.2checkout.com/api/products/detail_coupon \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'coupon_code=APITEST002'

Example Successful Response

 {
       "coupon" : {
          "coupon_code" : "APITEST002",
          "date_expire" : "2012-12-31",
          "minimum_purchase" : "5.00",
          "percentage_off" : "5",
          "product" : [
             {
                "product_id" : "0",
                "product_url" : "https://www.2checkout.com/api/products/detail_product?product_id=0"
             }
          ],
          "type" : "sale",
          "value_off" : null
       },
       "response_code" : "OK",
       "response_message" : "Coupon detail retrieved successfully."
    }

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to coupon.

List Coupons

Overview

The list_coupons call is used to retrieve list of all coupons in the account.

URL: https://www.2checkout.com/api/products/list_coupons

HTTP Method: GET

Input Parameters

No input parameters required.

Data Returned

coupon

Parameter Description
coupon_code The string value of coupon code.
vendor_id Merchant ID (2Checkout Account Number) of user.
date_expire Expiration Date.(YYYY-MM-DD)
percentage_off Percentage Discount.
value_off Fixed Discount.
type Coupon type.
minimum_purchase Minimum purchase amount.
product_id ID of product selected for coupon.

Example API Call

curl -G https://www.2checkout.com/api/products/list_coupons \
    -H 'Accept: application/json' -u 'username:password'

Example Successful Response

{
       "coupon" : [
          {
             "coupon_code" : "TESTPERCENT",
             "date_expire" : "2013-06-30",
             "minimum_purchase" : "1.00",
             "percentage_off" : "0.10",
             "type" : "product",
             "value_off" : null
          },
          {
             "coupon_code" : "APITEST002",
             "date_expire" : "2012-12-31",
             "minimum_purchase" : "5.00",
             "percentage_off" : "0.05",
             "type" : "sale",
             "value_off" : null
          },
          {
             "coupon_code" : "APITEST003",
             "date_expire" : "2012-12-31",
             "minimum_purchase" : "5.00",
             "percentage_off" : "0.01",
             "type" : "sale",
             "value_off" : null
          },
          {
             "coupon_code" : "APITEST004",
             "date_expire" : "2012-12-31",
             "minimum_purchase" : "5.00",
             "percentage_off" : "0.02",
             "type" : "sale",
             "value_off" : null
          },
          {
             "coupon_code" : "PERCENTALL",
             "date_expire" : "2012-05-04",
             "minimum_purchase" : "10.00",
             "percentage_off" : "0.10",
             "type" : "product",
             "value_off" : null
          }
       ],
       "response_code" : "OK",
       "response_message" : "Coupon information retrieved successfully."
    }

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.

Delete Option

Overview

The delete_option call is used to delete a product option.

URL: https://www.2checkout.com/api/products/delete_option

HTTP Method: POST


Input Parameters

Parameter Description
option_id ID of option to delete. Required.

Data Returned

Parameter Description
response_code Tells the user whether or not the operation was successful.
response_message Tells the user why the operation was or was not successful.

Example API Call

curl -X POST https://www.2checkout.com/api/products/delete_option \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'option_id=4709264206'

Example Successful Response

    {
       "response_code" : "OK",
       "response_message" : "Option deleted successfully"
    }

 


Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to option.

Update Option

Overview

The update_option call is used to update an option.

URL: https://www.2checkout.com/api/products/update_option

HTTP Method: POST


Input Parameters

Parameter Description
option_id ID of option being updated. Required.
option_name Name of new product option. Required.
option_value_id ID of existing option value to update/delete. Required when updating/deleting an option value.
option_value_name Name of option value. Required when creating an option value.
option_value_surcharge Amount of option surcharge. Required when creating an option value surcharge.

Data Returned

Parameter Description
response_code Tells the user whether or not the operation was successful.
response_message Tells the user why the operation was or was not successful.

Example API Call

curl -X POST https://www.2checkout.com/api/products/update_option \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'option_id=1001' -d 'option_name=test option' -d 'option_value_name=colors'
    -d 'option_value_surcharge=1.00'

Example Successful Response

    {
       "response_code" : "OK",
       "response_message" : "Option updated successfully"
    }

 


Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to option.

Create Option

Overview

The create_option call is used to create a new product option.

URL: https://www.2checkout.com/api/products/create_option

HTTP Method: POST


Input Parameters

Parameter Description
option_name Name of new product option. Required.
option_value_name Name of option value. Multiples allowed but must equal number of option_value_surcharges supplied (&option_value_name=xxxxxxxx&option_value_name=yyyyyyyyy). Required.
option_value_surcharge Amount of option value. Multiples allowed but must equal number of option_value_names supplied (&option_value_surcharge=xxxxxxxx&option_value_surcharge=yyyyyyyyy). Required.

Data Returned

Parameter Description
response_code Tells the user whether or not the operation was successful.
response_message Tells the user why the operation was or was not successful.
option_id ID assigned to the option by 2Checkout.

Example API Call

curl -X POST https://www.2checkout.com/api/products/create_option \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'option_name=test' -d 'option_value_name=red' -d 'option_value_surcharge=1.00' \
    -d 'option_value_name=blue' -d 'option_value_surcharge=1.00'

Example Successful Response

    {
       "option_id" : "1234567890",
       "response_code" : "OK",
       "response_message" : "Option created successfully"
    }

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:

Detail Product

Overview

The detail_product call is used to retrieve the details for a single product.

URL: https://www.2checkout.com/api/products/detail_product

HTTP Method: GET


Input Parameters

Parameter Description
product_id ID of product to retrieve details for. Required.

Data Returned

 

product

Parameter Description
product_id System Product ID.
name Product Name
vendor_product_id Merchant Assigned Product ID.
description Product Short Description.
long_description Product Long Description.
price Product Price.
tangible Tangible=1, Intangible=0.
weight Product Weight.
handling Product Handling Fee.
recurrence Product Recurrence.
startup_fee Recurring Startup Fee.
duration Product Duration.
assigned_product_id 2CO Assigned Product ID.
pending_url Product Pending URL.
approved_url Product Approved URL.
commission Affiliate commision.
commission_type Affiliate commision type.

 

images

Parameter Description
image_number Image number.
image_id Image ID.

 

options

Parameter Description
option_value_id Product option value.
option_id Product option ID.
option_name Product option name.
vendor_id Merchant ID (2Checkout Account Number) of user.
option_value_surcharge Option value surcharge.
option_value_name Option value name.

 

categories

Parameter Description
category_id Category ID
name Category name.
parent_id Category parent ID.
description Category description.
parent_name Category parent name.

Example API Call

curl -G https://www.2checkout.com/api/products/detail_product \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'product_id=4635212971'

Example Successful Response

 {
       "product" : {
          "approved_url" : null,
          "assigned_product_id" : "2559",
          "categories" : [],
          "commission" : 0,
          "commission_amount" : null,
          "commission_type" : null,
          "description" : "An API created product",
          "duration" : null,
          "handling" : null,
          "images" : [],
          "long_description" : null,
          "name" : "API product",
          "options" : [
             {
                "option_id" : "4023756741",
                "option_name" : "extra benefit",
                "option_values" : [
                   {
                      "option_value_id" : "4023756744",
                      "option_value_name" : "full life coverage",
                      "option_value_surcharge" : "1.00"
                   },
                   {
                      "option_value_id" : "4023756747",
                      "option_value_name" : "half life coverage",
                      "option_value_surcharge" : "0.50"
                   },
                   {
                      "option_value_id" : "4023756750",
                      "option_value_name" : "extra lives coverage",
                      "option_value_surcharge" : "2.00"
                   }
                ]
             },
             {
                "option_id" : "4688355343",
                "option_name" : "decibels",
                "option_values" : [
                   {
                      "option_value_id" : "4688355346",
                      "option_value_name" : "150dB",
                      "option_value_surcharge" : "11.00"
                   },
                   {
                      "option_value_id" : "4688441332",
                      "option_value_name" : "200dB",
                      "option_value_surcharge" : "22.00"
                   },
                   {
                      "option_value_id" : "4688441335",
                      "option_value_name" : "250dB",
                      "option_value_surcharge" : "33.00"
                   }
                ]
             }
          ],
          "pending_url" : null,
          "price" : "10.00",
          "product_id" : "4635212971",
          "recurrence" : null,
          "recurrence_p" : null,
          "recurring" : "0",
          "startup_fee" : null,
          "tangible" : "0",
          "vendor_id" : "606917",
          "vendor_product_id" : "",
          "weight" : null
       },
       "response_code" : "OK",
       "response_message" : "Product detail information retrieved successfully"
    }

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to product.

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo