2Checkout Instant Notification Service User Guide Changes Revision 1.0 to 1.1

Transcription

1 INS User Guide Changes 2Checkout Instant Notification Service User Guide Changes Table of Contents Overview...2 Messages Supported...2 Message Changes...2 New Messages...2 Message Parameters...2 New Values for message_type...2 Parameters Altered...3 Parameters Removed...3 Parameters Added...4 Summary of all parameters and changes...4 1

2 INS User Guide Changes Overview The Instant Notification Service (INS) underwent significant changes from. 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 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 Order Created Shipping Status Changed Invoice Status Changed Recurring Complete Recurring Restarted 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 Order Created Fraud Status Changed Shipping Status Changed Invoice Status Changed Refund Issued Recurring Installment Success Recurring Installment Failed Recurring Stopped Recurring Complete Value ORDER_CREATED FRAUD_STATUS_CHANGED SHIP_STATUS_CHANGED INVOICE_STATUS_CHANGED REFUND_ISSUED RECURRING_INSTALLMENT_SUCCESS RECURRING_INSTALLMENT_FAILED RECURRING_STOPPED RECURRING_COMPLETE 2

3 INS User Guide Changes Recurring Restarted RECURRING_RESTARTED Parameters Altered The following parameters have in name or value format: 1.0 Parameter NEW 1.1 Parameter What's message_type message_type Values sent have ; 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 usd_amount invoice_usd_amount cust_amount invoice_cust_amount first_name customer_first_name last_name customer_last_name rec_list_amount_# item_rec_list_amount_# rec_status item_rec_status_# rec_date_next item_rec_date_next_# installments_billed item_rec_install_billed_# Parameters Removed Four parameters have been removed: 1.0 Parameter What's rec_date_start (you can use the new parameter sale_date_placed in its place, if needed) item_quantity_# (you can assume quantity of 1 for each item sent) reattempt retry_at 3

4 INS User Guide Changes Parameters Added Additionally, several new parameters have been added: NEW 1.1 Parameter message_description sale_date_placed customer_ip Format / Description Text; Human readable description of message_type Date of sale; format YYYY-MM-DD HH:MM:SS 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 Vendor Admin item_list_amount_# Numeric; Total in vendor 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_# item_type_# Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) 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 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 ) message_description Text; Human readable description of message_type timestamp timestamp Timestamp of event; format YYYY-MM-DD HH:MM:SS md5_hash md5_hash UPPERCASE(MD5_ENCRYPTED(sale_id + vendor_id + invoice_id + Secret Word)); Can be used to validate authenticity of message message_id message_id Numeric; This number is incremented for each message sent to a given vendor. 4 Values sent have ; Ex. Sale created is now ORDER_CREATED Encryption algorithm now matches direct return encryption algorithm key_count key_count Numeric; Indicates the number of parameters sent in message vendor_id vendor_id Numeric; Vendor account number sale_id sale_id Numeric; 2Checkout sale number

5 INS User Guide Changes sale_date_placed Date of sale; format YYYY-MM-DD HH:MM:SS vendor_order_id vendor_order_id Text; Custom order id provided by vendor, if available. ("vendor_order_id" can be provided in the CGI handoff to 2Checkout's purchase routine) invoice_id invoice_id Numeric; 2Checkout invoice number; Each sale can have several invoices, most commonly one per installment billed on a recurring order. 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) list_currency list_currency 3-Letter ISO code for vendor currency cust_currency cust_currency 3-Letter ISO code for customer currency auth_exp auth_exp The date credit authorization will expire; format YYYY-MM-DD invoice_status invoice_status Text; Status of a transaction (approved, pending, deposited, or declined) 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 list_amount invoice_list_amount Numeric; Total in vendor pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) usd_amount invoice_usd_amount Numeric, Total in US Dollars; format with 2 decimal places cust_amount invoice_cust_amount Numeric; Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) first_name customer_first_name Text; Customer s first name (may not be available on older sales) last_name customer_last_name Text; Customer s last name (may not be available on older sales) customer_name customer_name Text; Customer s full name (name as it appears on credit card) customer_ customer_ Text; Customer s address customer_phone 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 bill_street_address Text; Billing street address bill bill_street_address2 Text; Billing street address line 2 _street_address2 bill _city bill_city Text; Billing address city bill _state bill_state Text; Billing address state or province bill _postal_code bill_postal_code Text; Billing address postal code bill _country bill_country Text; 3-Letter ISO country code of billing address ship_status Text; Value will be not_shipped, shipped, or empty (if intangible / does not need shipped) 5 ship_tracking_number Text; Tracking Number as entered in Vendor Admin ship_name ship_name shipping_.shipping_name (invoice_.shipping_id = shipping_.id) ship_street_addres s ship_street_address Text; Shipping street address

6 INS User Guide Changes ship_street_addres ship_street_address2 Text; Shipping street address line 2 s2 ship_city ship_city Text; Shipping address city ship_state ship_state Text; Shipping address state or province ship_postal_code ship_postal_code Text; Shipping address postal code ship_country ship_country Text; 3-Letter ISO country code of shipping address item_count item_count Numeric; Number of line items item_name_# item_name_# Text; Product name item_id_# item_id_# Text; Vendor product id item_list_amount_# Numeric; Total in vendor 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 Item_duration_# item_duration_# Text; Product duration, how long it re-bills for Ex. 1 Year item_recurrence_# item_recurrence_# Text; Product recurrence, how often it re-bills Ex. 1 Month rec_list_amount_# item_rec_list_amount_# Numeric; Product price; format as appropriate to currency (2 decimal places for most, integer for JPY) rec_status item_rec_status_# Text; indicates status of recurring subscription: live, canceled, or completed rec_date_next item_rec_date_next_# Date of next recurring installment; format YYYY-MM-DD installments_billed item_rec_install_billed_# Numeric; The number of successful recurring installments successfully billed rec_date_start item_quantity_# reattempt retry_at (you can use the new parameter sale_date_placed in its place, if needed) (you can assume quantity of 1 for each item sent) 6