Table of Contents
- Introduction
- INS System
- Overview
- Message Opt-In
- Message Specifications
- Messages Supported
- INS Message Parameters
- Parameters by message
- Message: Order Created
- Message: Fraud Status Changed
- Message: Shipping Status Changed
- Message: Invoice Status Changed
- Message: Refund Issued
- Message: Recurring Installment Success
- Message: Recurring Installment Failed
- Message: Recurring Stopped
- Message: Recurring Complete
- Message: Recurring Restarted
- Download INS User Guide
- Revision History
Introduction
The Instant Notification Service (INS) is designed to offer sellers a way to automate order management processes by accepting order information via web posts. This service has long been a top request of our sellers, and we believe there are thousands of 2Checkout sellers who will benefit greatly from this service.
INS is a service which will post sets of CGI 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).
INS System
Overview
As a 2Checkout seller, you can now opt to receive information about your orders via HTTP POST to a URL you specify.
Message Opt-In
As a 2Checkout seller, you can opt in to receive one, several, or all of the message types offered by 2Checkout. For each message type, you can specify the URL which you would like the messages to post to.
To opt-in, login to the new Seller Administration area located at https://www.2checkout.com/va/.
Select the Account tab, then the Notifications sub-tab.
Use the notification interface to enable or disable messages and set either a Global URL for receipt of all messages or individual URLs per message as needed.
Message Specifications
Messages Supported
Messages Supported:
- Order Created
- Fraud Status Changed
- Shipping Status Changed
- Invoice Status Changed
- Refund Issued
- Recurring Installment Success
- Recurring Installment Failed
- Recurring Stopped
- Recurring Complete
- Recurring Restarted
INS Message Parameters
The following tables describe the format of all parameters sent by the 2Checkout INS system as part of any message. The specific parameters to expect as part of each message depend on the message type, and are covered in more detail in later sections.
Document Conventions
| Abbreviations Used in This Document |
|---|
| YYYY is a 4-digit year, Ex. 2008 |
| MM is a 2-digit month, Ex. 01 for January, 12 for December |
| DD is a 2-digit date, Ex. 05 or 31 |
| HH is a 2-digit hour on a 24 hour clock, Ex 05 for 5am, 17 for 5pm |
| MM is a 2-digit minute, Ex. 03 or 59 |
| SS is a 2 -digit second, Ex. 04 or 45 |
| All times will be sent in U.S. Eastern Time |
| All parameters ending in _# will be sent as numbered sets (beginning with 1), one for each item. For example: |
|---|
| Item_count=2 |
| item_name_1=hosting |
| item_id_1=12 |
| item_list_amount_1=5.00 |
| item_usd_amount_1=2.50 |
| item_cust_amount_1=250 |
| item_type_1=bill |
| item_duration_1=1 Year |
| item_recurrence_1=1 Month |
| item_rec_list_amount_1=5.00 |
| item_rec_status_1=live |
| item_rec_date_next_1=2008-02-17 |
| item_rec_install_billed_1=1 |
| item_name_2=t-shirt |
| item_id_2=22 |
| item_quantity_2=1 |
| item_list_amount_2=3.00 |
| item_usd_amount_2=1.50 |
| item_cust_amount_2=150 |
| item_type_2=bill |
| item_duration_2= |
| item_recurrence_2= |
| item_rec_list_amount_2= |
| item_rec_status_2= |
| item_rec_date_next_2= |
| item_rec_install_billed_2= |
- Additional information about alpha-3 ISO currency codes: http://en.wikipedia.org/wiki/ISO_4217
- Additional information about ISO alpha-3 country codes: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
| Parameter Format | Description |
|---|---|
| message_type | Upper Case Text; Indicates type of message (ORDER_CREATED, FRAUD_STATUS_CHANGED, SHIP_STATUS_CHANGED, INVOICE_STATUS_CHANGED, REFUND_ISSUED, RECURRING_INSTALLMENT_SUCCESS, RECURRING_INSTALLMENT_FAILED, RECURRING_STOPPED, RECURRING_COMPLETE, or RECURRING_RESTARTED ) |
| message_description | Text; Human readable description of message_type |
| timestamp | Timestamp of event; format YYYY-MM-DD HH:MM:SS |
| md5_hash | Upper Case Text; UPPERCASE(MD5_ENCRYPTED(sale_id + vendor_id + invoice_id + Secret Word)); Can be used to validate authenticity of message |
| message_id | Numeric; This number is incremented for each message sent to a given seller. |
| key_count | Numeric; Indicates the number of parameters sent in message |
| vendor_id | Numeric; Seller account number |
| sale_id | Numeric; 2Checkout sale number |
| sale_date_placed | Date of sale; format YYYY-MM-DD HH:MM:SS |
| vendor_order_id | Text; Custom order id provided by seller, if available. ("merchant_order_id" can be provided in the CGI handoff to 2Checkout's purchase routine) |
| invoice_id | Numeric; 2Checkout invoice number; Each sale can have several invoices, most commonly one per installment billed on a recurring order. |
| recurring | Numeric; recurring=1 if any item on the invoice is a recurring item, 0 otherwise |
| payment_type | Lower Case Text; Customer’s payment method (credit card, online check, paypal ec, OR paypal pay later) |
| list_currency | Upper Case Text; 3-Letter ISO code for seller currency |
| cust_currency | Upper Case Text; 3-Letter ISO code for customer currency |
| auth_exp | The date credit authorization will expire; format YYYY-MM-DD |
| fraud_status | Lower Case Text; Status of 2Checkout fraud review (pass, fail, or wait); This parameter could be empty for some sales |
| invoice_status | Lower Case Text; Status of a transaction (approved, pending, deposited, or declined) |
| invoice_list_amount | Numeric; Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| invoice_usd_amount | Numeric, Total in US Dollars; format with 2 decimal places |
| invoice_cust_amount | Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| customer_first_name | Text; Customer’s first name (may not be available on older sales) |
| customer_last_name | Text; Customer’s last name (may not be available on older sales) |
| customer_name | Text; Customer’s full name (name as it appears on credit card) |
| customer_email | Text; Customer’s email address |
| customer_phone | Numeric; Customer’s phone number; all but digits stripped out |
| customer_ip | Text; Customer’s IP address at time of sale |
| customer_ip_country | Text; Country of record for customer's IP address at time of sale; Please note in some cases what is returned is not a country, Ex. Satellite Provider |
| bill_street_address | Text; Billing street address |
| bill_street_address2 | Text; Billing street address line 2 |
| bill_city | Text; Billing address city |
| bill_state | Text; Billing address state or province |
| bill_postal_code | Text; Billing address postal code |
| bill_country | Text; 3-Letter ISO country code of billing address |
| ship_status | Lower Case Text; Value will be not_shipped, shipped, or empty (if intangible / does not need shipped) |
| ship_tracking_number | Text; Tracking Number as entered in Seller Admin |
| ship_name | Text; Shipping Recipient’s name (as it should appear on shipping label) |
| ship_street_address | Text; Shipping street address |
| ship_street_address2 | Text; Shipping street address line 2 |
| ship_city | Text; Shipping address city |
| ship_state | Text; Shipping address state or province |
| ship_postal_code | Text; Shipping address postal code |
| ship_country | Upper Case Text; 3-Letter ISO country code of shipping address |
| item_count | Numeric; Indicates how many numbered sets of item parameters to expect |
| item_name_# | Text; Product name |
| item_id_# | Text; Seller product id |
| item_list_amount_# | Numeric; Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| item_usd_amount_# | Numeric, Total in US Dollars; format with 2 decimal places |
| item_cust_amount_# | Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| item_type_# | Lower Case Text; Indicates if item is a bill or refund; Value will be bill or refund |
| item_duration_# | Text; Product duration, how long it re-bills for Ex. 1 Year |
| item_recurrence_# | Text; Product recurrence, how often it re-bills Ex. 1 Month |
| item_rec_list_amount_# | Numeric; Product price; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| item_rec_status_# | Lower Case Text; indicates status of recurring subscription: live, canceled, or completed |
| item_rec_date_next_# | Date of next recurring installment; format YYYY-MM-DD |
| item_rec_install_billed_# | Numeric; The number of successful recurring installments successfully billed |
INS parameter descriptions and formats
| Parameter | Format / Description |
|---|---|
| message_type | Upper Case Text; Indicates type of message (ORDER_CREATED, FRAUD_STATUS_CHANGED, SHIP_STATUS_CHANGED, INVOICE_STATUS_CHANGED, REFUND_ISSUED, RECURRING_INSTALLMENT_SUCCESS, RECURRING_INSTALLMENT_FAILED, RECURRING_STOPPED, RECURRING_COMPLETE, or RECURRING_RESTARTED ) |
| message_description | Text; Human readable description of message_type |
| timestamp | Timestamp of event; format YYYY-MM-DD HH:MM:SS ZZZ |
| md5_hash | Upper Case Text; UPPERCASE(MD5_ENCRYPTED(sale_id + vendor_id + invoice_id + Secret Word)); Can be used to validate authenticity of message |
| message_id | Numeric; This number is incremented for each message sent to a given seller. |
| key_count | Numeric; Indicates the number of parameters sent in message |
| vendor_id | Numeric; Seller account number |
| sale_id | Numeric; 2Checkout sale number |
| sale_date_placed | Date of sale; format YYYY-MM-DD |
| vendor_order_id | Text; Custom order id provided by seller, if available. ("merchant_order_id" can be provided in the CGI handoff to 2Checkout's purchase routine) |
| invoice_id | Numeric; 2Checkout invoice number; Each sale can have several invoices, most commonly one per installment billed on a recurring order. |
| recurring | Numeric; recurring=1 if any item on the invoice is a recurring item, 0 otherwise |
| payment_type | Lower Case Text; Customer’s payment method (credit card, online check, paypal ec, OR paypal pay later) |
| list_currency | Upper Case Text; 3-Letter ISO code for seller currency |
| cust_currency | Upper Case Text; 3-Letter ISO code for customer currency |
| auth_exp | The date credit authorization will expire; format YYYY-MM-DD |
| invoice_status | Lower Case Text; Status of a transaction (approved, pending, deposited, or declined) |
| fraud_status | Lower Case Text; Status of 2Checkout fraud review (pass, fail, or wait); This parameter could be empty for some sales |
| invoice_list_amount | Numeric; Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| invoice_usd_amount | Numeric, Total in US Dollars; format with 2 decimal places |
| invoice_cust_amount | Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| customer_first_name | Text; Customer’s first name (may not be available on older sales) |
| customer_last_name | Text; Customer’s last name (may not be available on older sales) |
| customer_name | Text; Customer’s full name (name as it appears on credit card) |
| customer_email | Text; Customer’s email address |
| customer_phone | Numeric; Customer’s phone number; all but digits stripped out |
| customer_ip | Text; Customer’s IP address at time of sale |
| customer_ip_country | Text; Country of record for customer's IP address at time of sale; Please note in some cases what is returned is not a country, Ex. Satellite Provider |
| bill_street_address | Text; Billing street address |
| bill_street_address2 | Text; Billing street address line 2 |
| bill_city | Text; Billing address city |
| bill_state | Text; Billing address state or province |
| bill_postal_code | Text; Billing address postal code |
| bill_country | Text; 3-Letter ISO country code of billing address |
| ship_status | Lower Case Text; Value will be not_shipped, shipped, or empty (if intangible / does not need shipped) |
| ship_tracking_number | Text; Tracking Number as entered in Seller Admin |
| ship_name | Text; Shipping Recipient’s name (as it should appears on shipping label) |
| ship_street_address | Text; Shipping street address |
| ship_street_address2 | Text; Shipping street address line 2 |
| ship_city | Text; Shipping address city |
| ship_state | Text; Shipping address state or province |
| ship_postal_code | Text; Shipping address postal code |
| ship_country | Upper Case Text; 3-Letter ISO country code of shipping address |
| item_count | Numeric; Indicates how many numbered sets of item parameters to expect |
| item_name_# | Text; Product name |
| item_id_# | Text; Seller product id |
| item_list_amount_# | Numeric; Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| item_usd_amount_# | Numeric, Total in US Dollars; format with 2 decimal places |
| item_cust_amount_# | Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| item_type_# | Lower Case Text; Indicates if item is a bill or refund; Value will be bill or refund |
| item_duration_# | Text; Product duration, how long it re-bills for Ex. 1 Year |
| item_recurrence_# | Text; Product recurrence, how often it re-bills Ex. 1 Month |
| item_rec_list_amount_# | Numeric; Product price; format as appropriate to currency (2 decimal places for most, integer for JPY) |
| item_rec_status_# | Lower Case Text; indicates status of recurring subscription: live, canceled, or completed |
| item_rec_date_next_# | Date of next recurring installment; format YYYY-MM-DD |
| item_rec_install_billed_# | Numeric; The number of successful recurring installments successfully billed |
Parameters by message
| Key | |
|---|---|
| Invoice Level Message | |
| Item Level Message | |
| R | Required Field: will always have a value |
| O | Optional Field: may be empty |
| X | Field NOT included in message |
Invoice level messages contain all the information on an invoice, in other words, one set of item parameters for each item on an invoice.
Item level messages are specific to a particular product or service ordered; they contain exactly one set of item parameters (item_count will be 1 and all numbered item parameters will end in _1). Item level messages do not contain some of the invoice level information.
Both required and optional fields will always be sent, however, optional fields may be empty.
| INS Message Parameters | New Order Created | Fraud Status Changed | Shipping Status Changed | Invoice Status Changed | Refund Issued | Recurring Installment Success | Recurring Installment Failed | Recurring Stopped | Recurring Complete | Recurring Restarted |
|---|---|---|---|---|---|---|---|---|---|---|
| message_type | R | R | R | R | R | R | R | R | R | R |
| message_description | R | R | R | R | R | R | R | R | R | R |
| timestamp | R | R | R | R | R | R | R | R | R | R |
| md5_hash | R | R | R | R | R | R | R | R | R | R |
| message_id | R | R | R | R | R | R | R | R | R | R |
| key_count | R | R | R | R | R | R | R | R | R | R |
| vendor_id | R | R | R | R | R | R | R | R | R | R |
| sale_id | R | R | R | R | R | R | R | R | R | R |
| sale_date_placed | R | R | R | R | R | R | R | R | R | R |
| vendor_order_id | O | O | O | O | O | O | O | O | O | O |
| invoice_id | R | R | R | R | R | R | R | R | R | R |
| recurring | R | R | R | R | R | R | R | R | R | R |
| payment_type | R | R | R | R | R | R | R | R | R | R |
| list_currency | R | R | R | R | R | R | R | R | R | R |
| cust_currency | R | R | R | R | R | R | R | R | R | R |
| auth_exp | O | O | O | O | X | X | X | X | X | X |
| invoice_status | R | R | R | R | X | X | X | X | X | X |
| fraud_status | O | O | O | O | X | X | X | X | X | X |
| invoice_list_amount | R | R | R | R | X | X | X | X | X | X |
| invoice_usd_amount | R | R | R | R | X | X | X | X | X | X |
| invoice_cust_amount | R | R | R | R | X | X | X | X | X | X |
| customer_first_name | O | O | O | O | O | O | O | O | O | O |
| customer_last_name | O | O | O | O | O | O | O | O | O | O |
| customer_name | R | R | R | R | R | R | R | R | R | R |
| customer_email | R | R | R | R | R | R | R | R | R | R |
| customer_phone | R | R | R | R | R | R | R | R | R | R |
| customer_ip | O | O | O | O | O | O | O | O | O | O |
| customer_ip_country | O | O | O | O | O | O | O | O | O | O |
| bill_street_address | R | R | R | R | R | R | R | R | R | R |
| bill_street_address2 | O | O | O | O | O | O | O | O | O | O |
| bill_city | R | R | R | R | R | R | R | R | R | R |
| bill_state | O | O | O | O | O | O | O | O | O | O |
| bill_postal_code | O | O | O | O | O | O | O | O | O | O |
| bill_country | R | R | R | R | R | R | R | R | R | R |
| ship_status | O | O | O | O | O | O | O | O | O | O |
| ship_tracking_number | O | O | O | O | O | O | O | O | O | O |
| ship_name | O | O | O | O | O | O | O | O | O | O |
| ship_street_address | O | O | O | O | O | O | O | O | O | O |
| ship_street_address2 | O | O | O | O | O | O | O | O | O | O |
| ship_city | O | O | O | O | O | O | O | O | O | O |
| ship_state | O | O | O | O | O | O | O | O | O | O |
| ship_postal_code | O | O | O | O | O | O | O | O | O | O |
| ship_country | O | O | O | O | O | O | O | O | O | O |
| item_count | R | R | R | R | R | R | R | R | R | R |
| item_name_# | O | O | O | O | O | O | O | O | O | O |
| item_id_# | O | O | O | O | O | O | O | O | O | O |
| item_list_amount_# | R | R | R | R | R | R | R | R | R | R |
| item_usd_amount_# | R | R | R | R | R | R | R | R | R | R |
| item_cust_amount_# | R | R | R | R | R | R | R | R | R | R |
| item_type_# | R | R | R | R | R | R | R | R | R | R |
| item_duration_# | O | O | O | O | O | R | R | R | R | R |
| item_recurrence_# | O | O | O | O | O | R | R | R | R | R |
| item_rec_list_amount_# | O | O | O | O | O | R | R | R | R | R |
| item_rec_status_# | O | O | O | O | O | R | R | R | R | R |
| item_rec_date_next_# | O | O | O | O | O | R | R | R | R | R |
| item_rec_install_billed_# | O | O | O | O | O | R | R | R | R | R |
Within each message section page, the parameters highlighted in yellow, (like this *), are the parameters we believe will be most useful in updating your systems, or which are most relevant to that specific message.
NOTE: md5_hash values used in the following examples are NOT necessarily valid. MD5 is a data encryption algorithm which will help you validate that INS POSTs came from 2Checkout. >>More about MD5