2Checkout Documentation

Recurring Installment Failed

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 which 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_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 =>
        customer_first_name => Testing
        customer_ip =>
        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