I originally posted this article to x.com on August 3, 2010. Since that time, x.com has been repurposed, and my posts have been taken down. I have reposted this here for informational and historical purposes.
(Updated 8/9/2010 to include recurring_payment_expired)
There are several different values for the txn_type variable in an IPN message that are related to Recurring Payments:
- recurring_payment
- recurring_payment_failed
- recurring_payment_expired
- recurring_payment_suspended_due_to_max_failed_payment
- recurring_payment_profile_created
- recurring_payment_profile_cancel
- recurring_payment_outstanding_payment_failed
- recurring_payment_outstanding_payment
- recurring_payment_skipped
But, what do they all mean?
At one point in time, one of my merchants asked me this same question. I had a hell of a time (pardon my French) finding the answer — especially recurring_payment_skipped, which seems to be a pain point for many developers. Eventually, through talking to people internally and doing test cases, I managed to find the answers. I’ve had enough people ask me this same question that having the answer sitting around has been extremely useful.
- When the recurring payments profile is created, you receive an IPN with txn_type set to recurring_payment_profile_created.
- For each successful payment, you receive an IPN with txn_type set to recurring_payment.
- For each unsuccessful payment, you receive an IPN with txn_type set to recurring_payment_failed. The outstanding_balance field will have the amount currently outstanding.
- When the maximum number of failed payments is reached (as specified in the MAXFAILEDPAYMENTS parameter in your CreateRecurringPaymentsProfile call), you receive an IPN with txn_type set to recurring_payment_suspended_due_to_max_failed_payment. This is the only IPN you receive (e.g., if MAXFAILEDPAYMENTS was set to 1, you only receive this IPN on the failed payment; you do not receive another one with txn_type of recurring_payment_failed).
- If the recurring payments profile is cancelled, you receive an IPN with txn_type set to recurring_payment_profile_cancel.
- When the profile has “expired” (e.g., there are no more payments left on the profile, and the amount of time since the last payment plus the billing period has elapsed), you will get another IPN with txn_type set to recurring_payment_expired. This is intended to be a “reminder” to you that the buyer’s subscription is up, and to deactivate their service. For example, if you create a recurring payments profile on the 16th of the month, with a billing period of one month, and the profile is cancelled on the 28th of the month, you will get an IPN on the 28th with txn_type of recurring_payment_profile_cancel, and another IPN on the 16th of the next month with recurring_payment_expired.
Edit 3/8/2011: It’s been brought to my attention that recurring_payment_expired is only sent for Website Payments Standard subscriptions. I’m not entirely clear on all the details, but it appears that newer profiles (ones where the subscription ID starts with “I-“) will send recurring_payment_expired, whereas older profiles (ones where the subscription ID starts with “S-“) will send subscr_eot.
- If you call BillOutstandingAmount, the resulting IPN will have txn_type set to either recurring_payment_outstanding_payment_failed or recurring_payment_outstanding_payment. (Remember that if the profile has been suspended, you will need to call ManageRecurringPaymentsProfileStatus to reactivate the profile.)
- When you receive an IPN with txn_type set to recurring_payment_skipped, this means that, for some reason, PayPal was not able to process the recurring payment. This does not necessarily mean that the buyer’s credit card (or other funding source) was declined, but rather, it indicates that some other error occurred that prevented us from processing the payment. Because there are multiple reasons why this could happen, PayPal will make three attempts to charge the buyer — once after three days, and again five days after that. If the 3-day reattempt fails you will receive another IPN with txn_type set to recurring_payment_skipped. If the 5-day reattempt fails, the payment will be considered a failed payment, and you will receive an IPN with txn_type set to either recurring_payment_failed or recurring_payment_suspended_due_to_max_failed_payment, depending on how you set up the profile.