Table of Contents
Overview
The Instant Notification Service (INS) underwent significant changes from Revision 1.0 to 1.1. Both the messages provided, and the specific structure of all messages were revised and streamlined. The messages in 1.0 were each unique in structure, in 1.1 all messages share one of 2 structures, they are classified as item level or invoice level messages, and this classification indicates the message structure. Please see INS User Guide – Revision 1.1 for complete details of each message.
Messages Supported
Revision 1.1 provides several new messages, and no longer supports one of the 1.0 messages. Additionally, the names of several messages have been changed for clarity or brevity:
Message Changes
- Fraud Status Changed (replaces Order Fraud Status Changed from 1.0)
- Refund Issued (replaces Order Refunded from 1.0; also replaces Order Cancelled from 1.0
- Recurring Installment Success (replaces Recurring Installment Billing Succeeded from 1.0)
- Recurring Installment Failed (replaces Recurring Installment Billing Failed from 1.0)
- Recurring Stopped (replaces Recurring Order Stopped from 1.0)
New Messages
Message Parameters
Revision 1.1 includes several changes to existing parameters, primarily for clarity or disambiguation.
New Values for "message_type"
The message_type parameter is significant in particular as it indicates the specific message received. The new values for this parameter, by message, are:
| Message | Value |
|---|---|
| Order Created | ORDER_CREATED |
| Fraud Status Changed | FRAUD_STATUS_CHANGED |
| Shipping Status Changed | SHIP_STATUS_CHANGED |
| Invoice Status Changed | INVOICE_STATUS_CHANGED |
| Refund Issued | REFUND_ISSUED |
| Recurring Installment Success | RECURRING_INSTALLMENT_SUCCESS |
| Recurring Installment Failed | RECURRING_INSTALLMENT_FAILED |
| Recurring Stopped | RECURRING_STOPPED |
| Recurring Complete | RECURRING_COMPLETE |
| Recurring Restarted | RECURRING_RESTARTED |
Parameters Altered
The following parameters have changed in name or value format:
| 1.0 Parameter | NEW 1.1 Parameter | What's changed |
|---|---|---|
| message_type | message_type | Values sent have changed; Ex. Sale created is now ORDER_CREATED |
| md5_hash | md5_hash | Encryption algorithm now matches direct return encryption algorithm |
| recurring | recurring | Now sent with all messages |
| list_amount | invoice_list_amount | Parameter name has changed |
| usd_amount | invoice_usd_amount | Parameter name has changed |
| cust_amount | invoice_cust_amount | Parameter name has changed |
| first_name | customer_first_name | Parameter name has changed |
| last_name | customer_last_name | Parameter name has changed |
| rec_list_amount_# | item_rec_list_amount_# | Parameter name has changed |
| rec_status | item_rec_status_# | Parameter name has changed |
| rec_date_next | item_rec_date_next_# | Parameter name has changed |
| installments_billed | item_rec_install_billed_# | Parameter name has changed |
Parameters Removed
Four parameters have been removed:
| 1.0 Parameter | What's changed |
|---|---|
| rec_date_start | REMOVED (you can use the new parameter sale_date_placed in its place, if needed) |
| item_quantity_# | REMOVED (you can assume quantity of 1 for each item sent) |
| reattempt | REMOVED |
| retry_at | REMOVED |
Parameters Added
Additionally, several new parameters have been added:
| NEW 1.1 Parameter | Format / Description |
|---|---|
| message_description | Text; Human readable description of message_type |
| sale_date_placed | Date of sale; format YYYY-MM-DD HH:MM:SS |
| 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 |
| ship_status | 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 |
| 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_# | Text; Indicates if item is a bill (purchase) or refund; Value will be bill or refund |
Summary of all parameters and changes
| 1.0 Parameter | NEW 1.1 Parameter | 1.1 Format / Description | What's changed |
|---|---|---|---|
| message_type | message_type | 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) | Values sent have changed; Ex. Sale created is now ORDER_CREATED |
| message_description | Text; Human readable description of message_type | NEW! | |
| timestamp | timestamp | Timestamp of event; format YYYY-MM-DD HH:MM:SS | No change |
| md5_hash | md5_hash | UPPERCASE(MD5_ENCRYPTED(sale_id + vendor_id + invoice_id + Secret Word)); Can be used to validate authenticity of message | Encryption algorithm now matches direct return encryption algorithm |
| message_id | message_id | Numeric; This number is incremented for each message sent to a given seller. | No change |
| key_count | key_count | Numeric; Indicates the number of parameters sent in message | No change |
| vendor_id | vendor_id | Numeric; Seller account number | No change |
| sale_id | sale_id | Numeric; 2Checkout sale number | No change |
| sale_date_placed | Date of sale; format YYYY-MM-DD HH:MM:SS | NEW! | |
| vendor_order_id | vendor_order_id | Text; Custom order id provided by seller, if available. ("seller_order_id" can be provided in the CGI handoff to 2Checkout's purchase routine) | No change |
| invoice_id | invoice_id | Numeric; 2Checkout invoice number; Each sale can have several invoices, most commonly one per installment billed on a recurring order. | No change |
| recurring | recurring | Numeric; recurring=1 if any item on the invoice is a recurring item, 0 otherwise | Now sent with all messages |
| payment_type | payment_type | Text; Customer’s payment method (credit card, online check, mailed check, fxsource, paypal, bill me later, atmd, paypal ec, OR paypal pay later) | No change |
| list_currency | list_currency | 3-Letter ISO code for seller currency | No change |
| cust_currency | cust_currency | 3-Letter ISO code for customer currency | No change |
| auth_exp | auth_exp | The date credit authorization will expire; format YYYY-MM-DD | No change |
| invoice_status | invoice_status | Text; Status of a transaction (approved, pending, deposited, or declined) | No change |
| fraud_status | fraud_status | Lower Case Text; Status of 2Checkout fraud review (pass, fail, or wait); This parameter may be empty for some sales such as those placed using online check or fxsource | No change |
| list_amount | invoice_list_amount | Numeric; Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) | Parameter name has changed |
| usd_amount | invoice_usd_amount | Numeric, Total in US Dollars; format with 2 decimal places | Parameter name has changed |
| cust_amount | invoice_cust_amount | Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) | Parameter name has changed |
| first_name | customer_first_name | Text; Customer’s first name (may not be available on older sales) | Parameter name has changed |
| last_name | customer_last_name | Text; Customer’s last name (may not be available on older sales) | Parameter name has changed |
| customer_name | customer_name | Text; Customer’s full name (name as it appears on credit card) | No change |
| customer_email | customer_email | Text; Customer’s email address | No change |
| customer_phone | customer_phone | Numeric; Customer’s phone number; all but digits stripped out | No change |
| customer_ip | Text; Customer’s IP address at time of sale | NEW! | |
| 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 | NEW! | |
| bill_street_address | bill_street_address | Text; Billing street address | No change |
| bill_street_address2 | bill_street_address2 | Text; Billing street address line 2 | No change |
| bill_city | bill_city | Text; Billing address city | No change |
| bill_state | bill_state | Text; Billing address state or province | No change |
| bill_postal_code | bill_postal_code | Text; Billing address postal code | No change |
| bill_country | bill_country | Text; 3-Letter ISO country code of billing address | No change |
| ship_status | Text; Value will be not_shipped, shipped, or empty (if intangible / does not need shipped) | NEW! | |
| ship_tracking_number | Text; Tracking Number as entered in Seller Admin | NEW! | |
| ship_name | ship_name | shipping_.shipping_name (invoice_.shipping_id = shipping_.id) | No change |
| ship_street_address | ship_street_address | Text; Shipping street address | No change |
| ship_street_address2 | ship_street_address2 | Text; Shipping street address line 2 | No change |
| ship_city | ship_city | Text; Shipping address city | No change |
| ship_state | ship_state | Text; Shipping address state or province | No change |
| ship_postal_code | ship_postal_code | Text; Shipping address postal code | No change |
| ship_country | ship_country | Text; 3-Letter ISO country code of shipping address | No change |
| item_count | item_count | Numeric; Number of line items | No change |
| item_name_# | item_name_# | Text; Product name | No change |
| item_id_# | item_id_# | Text; Seller product id | No change |
| item_list_amount_# | Numeric; Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) | NEW! | |
| item_usd_amount_# | Numeric, Total in US Dollars; format with 2 decimal places | NEW! | |
| item_cust_amount_# | Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) | NEW! | |
| item_type_# | Text; Indicates if item is a bill (purchase) or refund; Value will be bill or refund | NEW! | |
| Item_duration_# | item_duration_# | Text; Product duration, how long it re-bills for Ex. 1 Year | No change |
| item_recurrence_# | item_recurrence_# | Text; Product recurrence, how often it re-bills Ex. 1 Month | No change |
| rec_list_amount_# | item_rec_list_amount_# | Numeric; Product price; format as appropriate to currency (2 decimal places for most, integer for JPY) | Parameter name has changed |
| rec_status | item_rec_status_# | Text; indicates status of recurring subscription: live, canceled, or completed | Parameter name has changed |
| rec_date_next | item_rec_date_next_# | Date of next recurring installment; format YYYY-MM-DD | Parameter name has changed |
| installments_billed | item_rec_install_billed_# | Numeric; The number of successful recurring installments successfully billed | Parameter name has changed |
| rec_date_start | REMOVED (you can use the new parameter sale_date_placed in its place, if needed) | ||
| item_quantity_# | REMOVED (you can assume quantity of 1 for each item sent) | ||
| reattempt | REMOVED | ||
| retry_at | REMOVED |