updates RSS feed

Hosted checkout parameters

Overview

These parameters can be used to dynamically pass in tangible/intangible and recurring/non-recurring products, product options, shipping, taxes, and coupons as items without having to create the products in the admin area.

Checkout URL

https://www.2checkout.com/checkout/purchase

Required Parameters

Parameter Description
sid Your 2Checkout account number.
mode Defines the parameter set. Should always be passed as ‘2CO’.
li_#_type The type of line item that is being passed in. (Always Lower Case, ‘product’, ‘shipping’, ‘tax’ or ‘coupon’, defaults to ‘product’)
li_#_name Name of the item passed in with the corresponding li_#_type. (128 characters max, cannot use ‘<' or '>’, defaults to capitalized version of ‘type’.)
li_#_quantity Quantity of the item passed in with the corresponding li_#_type. (0-999, defaults to 1 if not passed in.)
li_#_price Price of the line item. Format: 0.00-99999999.99, defaults to 0 if a value isn’t passed in, no negatives (use positive values for coupons), leading 0 & decimal are optional. Important note: If the li_#_price parameter isn’t used to pass in line item pricing, the pricing for the corresponding item will default to 0.00.
li_#_tangible Specifies if the corresponding li_#_type is a tangible or intangible. ( Must be Upper Case, ‘Y’ or ‘N’, if li_#_type is ‘shipping’ forced to ‘Y’.)



You can use these parameters to pass in multiple products as well. To do so you will need to append a digit to each parameter. For example, li_0_type, li_0_quantity, li_0_name, li_0_price, li_0_product_id, li_0_description, li_0_tangible will describe the first product, then to describe the second product you would increment so the parameters will read li_1_type, li_1_quantity, and so on. Please Note: With this parameter set # may be represented by 0-999 and aren’t required to be consecutive.

Additional Parameters

Parameter Description
li_#_product_id Id that you use to identify the product. 64 characters max, cannot use ‘<' or '>’.
li_#_description Description you use for the product. 255 characters max, cannot use ‘<' or '>’.
li_#_recurrence Sets billing frequency. Ex. ‘1 Week’ to bill order once a week. (Can use # Week, # Month, or # Year)
li_#_duration Sets how long to continue billing. Ex. ‘1 Year’, to continue billing based on li_#_recurrence for 1 year. (Forever or # Week, # Month, # Year)
li_#_startup_fee Any start up fees for the product or service. Can be negative to provide discounted first installment pricing, but cannot equal or surpass the product price.
li_#_option_#_name Name of product option. Ex. Size (64 characters max – cannot include ‘<' or '>’)
li_#_option_#_value Option selected. Ex. Small (64 characters max, cannot include ‘<' or '>’)
li_#_option_#_surcharge Option price in seller currency. (0.00 for no cost options)
demo Y to enable demo mode. Do not pass for live sales. Can also be controlled within the account.
currency_code AFN, ALL, DZD, ARS, AUD, AZN, BSD, BDT, BBD, BZD, BMD, BOB, BWP, BRL, GBP, BND, BGN, CAD, CNY, COP, CRC, CZK, DKK, DOP, XCD, EGP, EUR, FJD, GTQ, HKD, HNL, HUF, INR, IDR, ILS, JMD, JPY, KZT, KES, LAK, MMK, LBP, LRD, MOP, MYR, MVR, MRO, MUR, MXN, MAD, NPR, TWD, NZD, NIO, NOK, PKR, PGK, PEN, PHP, PLN, QAR, RON, RUB, WST, SAR, SCR, SGD, SBD, ZAR, KRW, LKR, SEK, CHF, SYP, THB, TOP, TTD, TRY, UAH, AED, USD, VUV, VND, XOF, YER. Use to specify the currency for the sale.
lang Chinese – zh, Danish – da, Dutch – nl, French – fr, German – gr, Greek – el, Italian – it, Japanese – jp, Norwegian – no, Portuguese – pt, Slovenian – sl, Spanish
merchant_order_id Specify your order number with this parameter. It will also be included in the confirmation emails to yourself and the customer. (50 characters max)
purchase_step Sets the purchase step that the buyer will land on when being directed to the checkout page. Possible values are ‘review-cart’, ‘shipping-information’, ‘shipping-method’, ‘billing-information’ and ‘payment-method’. Please Note: To skip a purchase step, all required fields must be pre-populated with the parameters that are passed in with the sale. If a required field is not pre-populated, the buyer will revert back to the step that needs to be completed.
x_receipt_link_url Used to specify an approved URL on-the-fly, but is limited to the same domain that is used for your 2Checkout account, otherwise it will fail. This parameter will over-ride any URL set on the Site Management page. (no limit)
coupon Specify a 2Checkout created coupon code. If applicable, the coupon will be automatically applied to the sale.



To pre-populate the billing information page you may pass in:

Parameter Description
card_holder_name Card holder’s name (128 characters max). The card holder’s name can also be populated using the first_name, middle_initial, and last_name parameters. IMPORTANT: If you use these three parameters, the data will be combined into and returned as card_holder_name to your Approved URL script.
street_address Card holder’s street address(64 characters max)
street_address2 The second line for the street address, typically suburb or apartment number information (64 characters max). Required if “country” value is: CHN, JPN, RUS - Optional for all other “country” values.
city Card holder’s city (64 characters max)
state Card holder’s state (64 characters max). Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values.
zip Card holder’s zip code/post code. Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values. (16 characters max)
country Card holder’s country (64 characters max)
email Card holder’s email (64 characters max)
phone Card holder’s phone (16 characters max)
phone_extension Card holder’s phone extension (9 characters max)



To pre-populate the shipping information page you may pass in:

Parameter Description
ship_name Recipient Name
ship_street_address Recipient Address 1
ship_street_address2 Recipient Address 2. Required if “ship_country” value is: CHN, JPN, RUS - Optional for all other “ship_country” values.
ship_city Recipient City
ship_state Recipient State. Required if “ship_country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “ship_country” values.
ship_zip Recipient Zip Code/Post Code. Required if “ship_country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “ship_country” values.
ship_country Recipient Country



The billing information page will also be populated with the information from the shipping page if the shipping information is collected on that sale and the billing information is not passed in.

Custom Parameters

You may pass in any additional parameters that you may need and they will be returned to you at the end of the sale. The only restrictions on custom parameters are that they can not share the name of ANY parameter that our system uses, even from the other sets. Please note that you WILL need a return script set up on the Site Management page to receive any of these parameters back as they are not included in the confirmation emails.

Parameters Returned

You will receive back all of the parameters that were passed in as well as the following parameters:

Parameter Description
order_number 2Checkout order number
invoice_id 2Checkout invoice id
credit_card_processed Y if successful (Approved).
total the total amount of the purchase
key the MD5 hash used to verify that the sale came from one of our servers

Important: You can not mix parameter sets. This will cause problems during payment or may prevent the payment pages from working at all.

Standard checkout

Overview

Our Standard Checkout option provides a complete checkout solution that can handle every part of the buyer’s checkout process on a single page. You can tailor the whole checkout process to your needs by passing in billing/shipping information, currency, language, and checkout steps.

Integration

Standard Checkout can be utilized by passing the required hosted checkout parameters to our checkout URL as shown in the examples below.

Multiple Lineitem Example

This sale includes 1 product with a quantity of 2, a coupon deduction, and both shipping and tax surcharges. The form also passes in all the billing and shipping information.

<form action='https://www.2checkout.com/checkout/purchase' method='post'>
<input type='hidden' name='sid' value='1303908' >
<input type='hidden' name='mode' value='2CO' >
<input type='hidden' name='li_0_type' value='product' >
<input type='hidden' name='li_0_name' value='Example Product Name' >
<input type='hidden' name='li_0_product_id' value='Example Product ID' >
<input type='hidden' name='li_0__description' value='Example Product Description' >
<input type='hidden' name='li_0_price' value='10.00' >
<input type='hidden' name='li_0_quantity' value='2' >
<input type='hidden' name='li_0_tangible' value='Y' >
<input type='hidden' name='li_1_type' value='shipping' >
<input type='hidden' name='li_1_name' value='Example Shipping Method' >
<input type='hidden' name='li_1_price' value='1.50' >
<input type='hidden' name='li_2_type' value='coupon' >
<input type='hidden' name='li_2_name' value='Example Coupon' >
<input type='hidden' name='li_2_price' value='1.00' >
<input type='hidden' name='li_3_type' value='tax' >
<input type='hidden' name='li_3_name' value='Example Tax' >
<input type='hidden' name='li_3_price' value='0.50' >
<input type='hidden' name='card_holder_name' value='Checkout Shopper' >
<input type='hidden' name='street_address' value='123 Test St >
<input type='hidden' name='street_address2' value='Suite 200' >
<input type='hidden' name='city' value='Columbus' >
<input type='hidden' name='state' value='OH' >
<input type='hidden' name='zip' value='43228' >
<input type='hidden' name='country' value='USA' >
<input type='hidden' name='email' value='example@2co.com' >
<input type='hidden' name='phone' value='614-921-2450' >
<input type='hidden' name='phone_extension' value='197' >
<input type='hidden' name='ship_name' value='Gift Receiver' >
<input type='hidden' name='ship_street_address' value='1234 Address Road' >
<input type='hidden' name='ship_street_address2' value='Apartment 123' >
<input type='hidden' name='ship_city' value='Columbus' >
<input type='hidden' name='ship_state' value='OH' >
<input type='hidden' name='ship_zip' value='43235' >
<input type='hidden' name='ship_country' value='USA' >
<input name='submit' type='submit' value='Checkout' >
</form>

Skipping Checkout Steps

You can use the ‘purchase_step’ parameter to set the purchase step that the buyer will land on when being directed to the checkout page. Possible values are ‘review-cart’, ‘shipping-information’, ‘shipping-method’, ‘billing-information’, and ‘payment-method’. Please Note: To skip a purchase step, all required fields must be pre-populated with the parameters that are passed in with the sale. If a required field is not pre-populated, the buyer will revert back to the step that needs to be completed.

Example form, Skipping Checkout Steps

<form action='https://www.2checkout.com/checkout/purchase' method='post'>
<input type='hidden' name='sid' value='1303908' >
<input type='hidden' name='mode' value='2CO' >
<input type='hidden' name='li_0_type' value='product' >
<input type='hidden' name='li_0_name' value='Example Product Name' >
<input type='hidden' name='li_0_product_id' value='Example Product ID' >
<input type='hidden' name='li_0__description' value='Example Product Description' >
<input type='hidden' name='li_0_price' value='10.00' >
<input type='hidden' name='li_0_quantity' value='2' >
<input type='hidden' name='li_0_tangible' value='N' >
<input type='hidden' name='card_holder_name' value='Checkout Shopper' >
<input type='hidden' name='street_address' value='123 Test St' >
<input type='hidden' name='street_address2' value='Suite 200' >
<input type='hidden' name='city' value='Columbus' >
<input type='hidden' name='state' value='OH' >
<input type='hidden' name='zip' value='43228' >
<input type='hidden' name='country' value='USA' >
<input type='hidden' name='email' value='example@2co.com' >
<input type='hidden' name='phone' value='614-921-2450' >
<input type='hidden' name='phone_extension' value='197' >
<input type='hidden' name='purchase_step' value='payment-method' >
<input name='submit' type='submit' value='Checkout' >
</form>

Return Process

Standard Checkout and Inline Checkout share the same return processes.

Hosted Checkout API

Overview

2Checkout sales are placed by the buyer through our secure checkout. You can pass the buyer to our Standard Checkout or for more seamless integration, you can display the payment form on your website using our Inline Checkout. You can easily customize the look and feel of the Standard Checkout page or Inline Checkout form using our Custom Checkout feature. By integrating with either checkout option, you automatically become PCI compliant as all sensitive card details are handled by us on our Level 1 PCI compliant servers. (Please Note: Our Inline Checkout option is presented in an iframe so we recommend that you use an SSL certificate on your checkout page. This way the buyer will be able to see that they are on a secure connection.) Integration can be completed by using our Hosted Checkout parameters which allow you to dynamically pass in both recurring and non-recurring product, shipping, tax, and coupon lineitems.

2checkout flowchart

Creating a Sale

You can initiate a new sale from your website or application by creating an HTML form or link to pass the buyer and sale parameters from your website to our checkout URL.

Example form

<form action='https://www.2checkout.com/checkout/purchase' method='post'>
  <input type='hidden' name='sid' value='1303908' />
  <input type='hidden' name='mode' value='2CO' />
  <input type='hidden' name='li_0_type' value='product' />
  <input type='hidden' name='li_0_name' value='Monthly Subscription' />
  <input type='hidden' name='li_0_price' value='1.00' />
  <input type='hidden' name='li_0_recurrence' value='1 Month' />
  <input name='submit' type='submit' value='Checkout' />
</form>

The buyer will then be able to enter their billing information and complete the checkout process using their preferred currency and payment method. Please review our Hosted Checkout parameters documentation for more information.

Handle the Passback

When the sale is completed, we will return the buyer and sale parameters back to the approved URL that you defined. The approved URL can be defined at the account level (under the Account tab and the Site Management sub-tab), at the product level (Plug and Play products only), or at the sale level (by passing in the x_receipt_link_url parameter). This way you can validate the passback and display your confirmation to the buyer. If no approved URL is defined, the buyer will be presented with a default order confirmation page providing an order summary, as well as a confirmation indicating that the payment is being processed.

Example Passback Validation

<?php
$hashSecretWord = 'tango'; //2Checkout Secret Word
$hashSid = 1303908; //2Checkout account number
$hashTotal = '1.00'; //Sale total to validate against
$hashOrder = $_REQUEST['order_number']; //2Checkout Order Number
$StringToHash = strtoupper(md5($hashSecretWord . $hashSid . $hashOrder . $hashTotal));
if ($StringToHash != $_REQUEST['key']) {
  $result = 'Fail - Hash Mismatch';
} else {
  $result = 'Success - Hash Matched';
}
echo $result;

Each of our community-supported libraries provides a binding to validate the hash on the passback to your approved URL.

Recurring complete

Overview

Recurring orders bill automatically according to schedule, which ends a fixed amount of time after original order placement. This message will allow sellers to automate any processes which should be keyed off completion of installment billing, such as issuing permanent credentials or account closure.

Please Note: The RECURRING_INSTALLMENT_SUCCESS message will also be sent prior to the RECURRING_COMPLETE message.

Recurring Complete is an item-level message; it will be sent once for each recurring item completed and will only contain information about that item.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        bill_city => Columbus
        bill_country => USA
        bill_postal_code => 43123
        bill_state => OH
        bill_street_address => 123 Test St
        bill_street_address2 => dddsdsc
        cust_currency => USD
        customer_email => testbuyer@2co.com
        customer_first_name => Craig
        customer_ip => 66.194.132.135
        customer_ip_country => United States
        customer_last_name => Christenson
        customer_name => Craig P Christenson
        customer_phone => 5555555555
        invoice_id => 4808173369
        item_count => 1
        item_cust_amount_1 => 0.01
        item_duration_1 => 1 Month
        item_id_1 => ebook2
        item_list_amount_1 => 0.01
        item_name_1 => updated product name
        item_rec_date_next_1 => 2012-09-22
        item_rec_install_billed_1 => 5
        item_rec_list_amount_1 => 0.01
        item_rec_status_1 => live
        item_recurrence_1 => 1 Week
        item_type_1 => bill
        item_usd_amount_1 => 0.01
        key_count => 50
        list_currency => USD
        md5_hash => 78327F2B9F1F98010354481745739027
        message_description => All installments billed
        message_id => 4491
        message_type => RECURRING_COMPLETE
        payment_type => paypal ec
        recurring => 1
        sale_date_placed => 2012-08-18 15:49:46
        sale_id => 4786306576
        ship_city => 
        ship_country => 
        ship_name => 
        ship_postal_code => 
        ship_state => 
        ship_status => 
        ship_street_address => 
        ship_street_address2 => 
        ship_tracking_number => 
        timestamp => 2012-09-15 02:43:45
        vendor_id => 532001
        vendor_order_id => test123
    }

 

Recurring installment failed

Overview

Recurring orders bill automatically according to schedule, but billings are not always successful. This message will allow you to automate any processes which should be keyed off installment billing failure, such as suspension of login credentials.

This message will send the information based on the last successful installment billed, in other words, the invoice number is the last invoice successfully billed, installments_billed is not incremented, and date_next will often be a date in the past, indicating the original due date for the missed billing.

Recurring Installment Failed is an item-level message; it will be sent once for each recurring item that fails to bill and will only contain information about that item.

Please Note: This message will be identical (except for timestamp) whether it is the first attempt or a retry.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        bill_city => Columbus
        bill_country => USA
        bill_postal_code => 43228
        bill_state => OH
        bill_street_address => ​855 Grandview Avenue
        bill_street_address2 => Suite 11
        cust_currency => LTL
        customer_email => cchristenson@2co.com
        customer_first_name => Testing
        customer_ip => 192.168.2.201
        customer_ip_country => Unknown
        customer_last_name => Tester
        customer_name => Tester
        customer_phone => 6149212450
        invoice_id => 4679675991
        item_count => 1
        item_cust_amount_1 => 0.03
        item_duration_1 => Forever
        item_id_1 => ebook1
        item_list_amount_1 => 0.01
        item_name_1 => Download
        item_rec_date_next_1 => 2012-04-16
        item_rec_install_billed_1 => 1
        item_rec_list_amount_1 => 0.01
        item_rec_status_1 => live
        item_recurrence_1 => 1 Week
        item_type_1 => bill
        item_usd_amount_1 => 0.01
        key_count => 50
        list_currency => USD
        md5_hash => 60C4032DF4929EA493B1E0338158A0F6
        message_description => Recurring installment failed to bill
        message_id => 3071
        message_type => RECURRING_INSTALLMENT_FAILED
        payment_type => credit card
        recurring => 1
        sale_date_placed => 2012-04-09 10:10:27
        sale_id => 4679675970
        ship_city => Columbus
        ship_country => USA
        ship_name => Testing Tester
        ship_postal_code => 43215
        ship_state => OH
        ship_status => shipped
        ship_street_address => ​855 Grandview Avenue
        ship_street_address2 => Suite 11
        ship_tracking_number => 
        timestamp => 2012-04-30 06:22:07
        vendor_id => 532001
        vendor_order_id => test123
    }

 

Recurring installment success

Overview

Recurring orders bill automatically according to schedule. This message will allow you to automate any processes which should be keyed off successful installment billing, such as an extension of login credentials.

This message will send the same customer information and sale_id (and vendor_order_id, if provided) as the original Order Created message, however, the successful billing will have generated a new invoice_id and will have incremented the item_rec_install_billed_# parameter.

Recurring Installment Success is an item-level message; it will be sent once for each recurring item billed successfully and will only contain information about that item.

Please Note: This message will be identical (except for timestamp) whether it is the first attempt or a retry.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        bill_city => Columbus
        bill_country => USA
        bill_postal_code => 43123
        bill_state => OH
        bill_street_address => 123 Test St
        bill_street_address2 => dddsdsc
        cust_currency => USD
        customer_email => noreply@2co.com
        customer_first_name => Craig
        customer_ip => 66.194.132.135
        customer_ip_country => United States
        customer_last_name => Christenson
        customer_name => Craig P Christenson
        customer_phone => 5555555555
        invoice_id => 4796973443
        item_count => 1
        item_cust_amount_1 => 0.01
        item_duration_1 => 
        item_id_1 => 
        item_list_amount_1 => 0.01
        item_name_1 => Example Product
        item_rec_date_next_1 => 2012-09-08
        item_rec_install_billed_1 => 5
        item_rec_list_amount_1 => 0.01
        item_rec_status_1 => live
        item_recurrence_1 => 1 Week
        item_type_1 => bill
        item_usd_amount_1 => 0.01
        key_count => 50
        list_currency => USD
        md5_hash => 63556765B734671F3341A6E659D7C6B6
        message_description => Recurring installment successfully billed
        message_id => 133
        message_type => RECURRING_INSTALLMENT_SUCCESS
        payment_type => paypal ec
        recurring => 1
        sale_date_placed => 2012-08-04 15:50:06
        sale_id => 4774475247
        ship_city => 
        ship_country => 
        ship_name => 
        ship_postal_code => 
        ship_state => 
        ship_status => 
        ship_street_address => 
        ship_street_address2 => 
        ship_tracking_number => 
        timestamp => 2012-09-01 03:16:26
        vendor_id => 1817037
        vendor_order_id => test123
    }

 

Recurring restarted

Overview

After being stopped, recurring orders can be restarted by 2Checkout staff for a variety of reasons, the most common being per buyer request. In this most common case, a customer calls 2Checkout and requests to restart billing on a recurring order.

Recurring Restarted is an item-level message; it will be sent once for each recurring item restarted and will only contain information about that item.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        message_type => RECURRING_RESTARTED
        message_description => Recurring order restarted
        timestamp => 2012-09-22 08:27:45
        message_id => 4666
        vendor_id => 532001
        vendor_order_id => 
        invoice_id => 4805798416
        recurring => 1
        list_currency => USD
        cust_currency => USD
        payment_type => paypal ec
        sale_id => 4783469055
        sale_date_placed => 2012-08-15 06:12:33
        customer_ip => 192.168.2.201
        customer_ip_country => Unknown
        customer_first_name => Testing
        customer_last_name => Tester
        customer_name => Testing  Tester
        customer_email => no-reply@2co.com
        customer_phone => 6149212450
        ship_status => 
        ship_tracking_number => 
        ship_name => 
        ship_street_address => 
        ship_street_address2 => 
        ship_city => 
        ship_state => 
        ship_postal_code => 
        ship_country => 
        bill_street_address => ​855 Grandview Avenue
        bill_street_address2 => Suite 11
        bill_city => Columbus
        bill_state => OH
        bill_postal_code => 43215
        bill_country => USA
        item_count => 1
        item_name_1 => test product
        item_id_1 => ebook1
        item_list_amount_1 => 0.10
        item_usd_amount_1 => 0.10
        item_cust_amount_1 => 0.10
        item_type_1 => bill
        item_duration_1 => 
        item_recurrence_1 => 1 Week
        item_rec_list_amount_1 => 0.10
        item_rec_status_1 => live
        item_rec_date_next_1 => 2012-09-19
        item_rec_install_billed_1 => 5
        md5_hash => C12DFC68837CCB63992E6DB1A3F9C9B5
        key_count => 50
    }

 

Recurring stopped

Overview

Recurring orders can be stopped by the buyer or the seller. This message will notify you when a recurring sale has been stopped so that you can disable the buyer’s service in your application.

Recurring Stopped is an item-level message; it will be sent once for each recurring item stopped and will only contain information about that item.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        message_type => RECURRING_STOPPED
        message_description => Recurring order stopped
        timestamp => 2012-10-16 20:21:49
        message_id => 289
        vendor_id => 1817037
        vendor_order_id => test123
        invoice_id => 4832772530
        recurring => 1
        list_currency => USD
        cust_currency => USD
        payment_type => paypal ec
        sale_id => 4832772521
        sale_date_placed => 2012-10-16 20:19:26
        customer_ip => 76.181.170.90
        customer_ip_country => United States
        customer_first_name => Testing
        customer_last_name => Tester
        customer_name => Testing Tester
        customer_email => testbuyer@2co.com
        customer_phone => 5555555555
        ship_status =>
        ship_tracking_number =>
        ship_name =>
        ship_street_address =>
        ship_street_address2 =>
        ship_city =>
        ship_state =>
        ship_postal_code =>
        ship_country =>
        bill_street_address => 123 Test St
        bill_street_address2 => dddsdsc
        bill_city => Columbus
        bill_state => OH
        bill_postal_code => 43123
        bill_country => USA
        item_count => 1
        item_name_1 => Example Product
        item_id_1 => example123
        item_list_amount_1 => 0.01
        item_usd_amount_1 => 0.01
        item_cust_amount_1 => 0.01
        item_type_1 => bill
        item_duration_1 =>
        item_recurrence_1 => 1 Week
        item_rec_list_amount_1 => 0.01
        item_rec_status_1 => live
        item_rec_date_next_1 => 2012-10-23
        item_rec_install_billed_1 => 1
        md5_hash => 7BC95622BF602363F49DE0E95CFF314C
        key_count => 50
    }

 

Refund issued

Overview

A refund is any credit issued back to the buyer. Refunds can be for specific products/items, or “partial” (no specific product is specified). They will always be specific to a single invoice. This message will allow you to automate more accurate inventory and financial tracking.

Refund Issued is an item-level message; it will be sent once for each refund item issued (product or partial) and will only contain information about that item.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        bill_city => Columbus
        bill_country => USA
        bill_postal_code => 43123
        bill_state => OH
        bill_street_address => 123 Test St
        bill_street_address2 => 
        cust_currency => USD
        customer_email => christensoncraig@gmail.com
        customer_first_name => Craig
        customer_ip => 66.194.132.135
        customer_ip_country => United States
        customer_last_name => Christenson
        customer_name => Craig P Christenson
        customer_phone => 5555555555
        invoice_id => 4707205064
        item_count => 1
        item_cust_amount_1 => 0.01
        item_duration_1 => 2 Month
        item_id_1 => ebook2
        item_list_amount_1 => 0.01
        item_name_1 => test recurring product
        item_rec_date_next_1 => 
        item_rec_install_billed_1 => 1
        item_rec_list_amount_1 => 0.01
        item_rec_status_1 => 
        item_recurrence_1 => 1 Week
        item_type_1 => refund
        item_usd_amount_1 => 0.01
        key_count => 50
        list_currency => USD
        md5_hash => 4CE10772450EFAC086E1F7667576128D
        message_description => Refund issued
        message_id => 3197
        message_type => REFUND_ISSUED
        payment_type => credit card
        recurring => 1
        sale_date_placed => 2012-05-14 06:29:53
        sale_id => 4707205055
        ship_city => 
        ship_country => 
        ship_name => 
        ship_postal_code => 
        ship_state => 
        ship_status => 
        ship_street_address => 
        ship_street_address2 => 
        ship_tracking_number => 
        timestamp => 2012-05-14 06:34:26
        vendor_id => 532001
        vendor_order_id => test123
    }

 

Ship status changed

Overview

This message indicates that the ship_status of an order has changed, from ‘not_shipped’ to shipped (e.g. when an order is marked shipped).

Ship Status Changed is an invoice level message; it will be sent once for each shipping status change on an invoice and will contain information about all items ordered.

Message Parameters

Parameter Type 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 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 Date of sale; format YYYY-MM-DD
vendor_order_id Text Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters)
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 Buyer’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 buyer currency
auth_exp Date 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 on 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 buyer currency; format as appropriate to currency (2 decimal places for most, integer for JPY)
customer_first_name Text Buyer’s first name (may not be available on older sales)
customer_last_name Text Buyer’s last name (may not be available on older sales)
customer_name Text Buyer’s full name (name as it appears on credit card)
customer_email Text Buyer’s email address
customer_phone Numeric Buyer’s phone number; all but digits stripped out
customer_ip Text Buyer’s IP address at time of sale
customer_ip_country Text Country of record for buyer’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 buyer 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 Date of next recurring installment; format YYYY-MM-DD
item_rec_install_billed_# Numeric The number of successful recurring installments successfully billed

Example message

{
        auth_exp => 2012-04-11
        bill_city => Columbus
        bill_country => USA
        bill_postal_code => 43215
        bill_state => OH
        bill_street_address => ​855 Grandview Avenue
        bill_street_address2 => Suite 11
        cust_currency => USD
        customer_email => no-reply@2checkout.com
        customer_first_name => Testing
        customer_ip => 66.194.132.135
        customer_ip_country => United States
        customer_last_name => Tester
        customer_name => Testing T Tester
        customer_phone => 6149212450
        fraud_status => wait
        invoice_cust_amount => 1.00
        invoice_id => 4676292911
        invoice_list_amount => 1.00
        invoice_status => pending
        invoice_usd_amount => 1.00
        item_count => 2
        item_cust_amount_1 => 1.00
        item_cust_amount_2 => 0.00
        item_duration_1 =>
        item_duration_2 =>
        item_id_1 => program1
        item_id_2 =>
        item_list_amount_1 => 1.00
        item_list_amount_2 => 0.00
        item_name_1 => test tangible
        item_name_2 => Shipping: free
        item_rec_date_next_1 =>
        item_rec_date_next_2 =>
        item_rec_install_billed_1 =>
        item_rec_install_billed_2 =>
        item_rec_list_amount_1 =>
        item_rec_list_amount_2 =>
        item_rec_status_1 =>
        item_rec_status_2 =>
        item_recurrence_1 =>
        item_recurrence_2 =>
        item_type_1 => bill
        item_type_2 => bill
        item_usd_amount_1 => 1.00
        item_usd_amount_2 => 0.00
        key_count => 68
        list_currency => USD
        md5_hash => 51D583E49E661FB64FD51D8505F3CCA1
        message_description => Shipping status changed
        message_id => 2807
        message_type => SHIP_STATUS_CHANGED
        payment_type => paypal ec
        recurring => 0
        sale_date_placed => 2012-04-04 13:56:26
        sale_id => 4676292902
        ship_city => Columbus
        ship_country => USA
        ship_name => Testing Tester
        ship_postal_code => 43215
        ship_state => OH
        ship_status => shipped
        ship_street_address => ​855 Grandview Avenue
        ship_street_address2 => Suite 11
        ship_tracking_number => 123
        timestamp => 2012-04-04 13:58:20
        vendor_id => 532001
        vendor_order_id =>
    }

 

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.

Get in touch

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.

Contact sales Get Started
Verifone logo