Paypal subscriptions IPN demystified

Recently I got a chance to work with PayPal Subscriptions Payment integration for recurring payments in one of my client’s website. PayPal indeed takes away all the hassles of charging/collecting recurring payments from your customers for any kind of service or subscription you intend to provide online. However, from the implementation perspective as a developer this is no easy job, especially amidst the confusing resources out there on the net including to much extent the Paypal documentation itself, and lack of proper test tools to test the integration. Lack of proper test tool in this situation forces you every time to make a guess out of the confusion, implement your guess, and wait for minimum a day or two to find out it won’t work the way you expected. However you have to live with it and this post serves as a kind of quick reference and yet another resource (and I hope not confusing) for any one trying to implement Paypal Subscription services.

Its a kind of an extract of the few days research that I did and it addresses the most common problem that developer might face while implementing the Paypal Subscription Payment method.

To automate the back office tasks Paypal provides its well know IPN (Instant Payment Notifications) notification for its recurring/subscription payment method as well. This helps you to automate the routine tasks that you might have to do manually otherwise. Paypal sends number of IPN notifications to a script on your server when ever a recurring payment is made, or canceled, or failed after N number of attempts. PayPal also manages to automatically bill your customer’s account after every defined period. However the most confusing part could be the IPN responses/transaction types that are sent on different events by the Paypal Server. I have tried to explain what each transaction types mean in context of recurring subscription payments method. I got this confirmed from the good guys at the PayPal forums.

The PayPal IPN Responses for the Subscription Payment Method

• subscr_signup: This IPN response (txn_type) is sent ONLY the very first time the user sign up for a subscription. It then does not fire in any event later. This response is received somewhere before or after the first payment of subscription is received (txn_type=subscr_payment).
  Important: When the payment fails, subscr_signup IPN response will not be sent.
• subscr_payment: This IPN response (txn_type) is sent EVERY time a successfull payment is recieved for a subscription, including when the customer sign up for the first time. So basically during the first signup you expect two separate IPN responses (subscr_payment & subscr_signup) in an short intervals.
• subscr_cancel: This IPN response (txn_type) is sent ONLY when either the subscriber cancels his/her current subscription or the merchant cancels the subscribers subscription. In this event according to new Paypal rules the subscr_eot (End of Term) IPN response is NEVER sent, and it is upto you to keep the subscription of the subscriber acitve for remaining days of subscription should they cancel their subscription in the middle of the subscription period.
• subscr_modify: This IPN response (txn_type) is sent WHENEVER the subscriber modifies their current subscription. Variable subscr_effective could be used to get the actual date the modified subscription becomes active.
  Important: If the subscribers modify their plan, there will not be any new subscr_signup IPN recieved when the new subscription becomes effective or during the first payment of the modified plan. subscr_signup is only sent for the initial sign-up
• subscr_eot: This IPN response (txn_type) is sent ONLY when the subscription ends naturally/expires. This will be sent on the same day the payment is received for the last subscription. So for example, I have a 3 months subscription recurring monthly and on every 1st date a customer is charged automatically then on the last month of subscription (3rd month in this case) I would receive the subscr_eot response on the very day the subscribers payment is received; in this case the 1st date of month and NOT the last day of the month, when the total subscription days actually get over.
  Important: Also based on the profile ID there is some differences on the way above IPN response works. For newer profiles, those begining with ‘I’ follow the above rule. Below is a detailed difference between the old and new profiles:
• If your profile ID starts with I- then your EOT IPN works as follows:
  If the profile is canceled then you never get an EOT IPN. Updated May 09 2011: If the profile is canceled then you get an EOT at the end of the time that the buyer paid for.
  If the profile naturally ends then you will get an EOT IPN right when the final payment is made. You will not get an IPN when the time paid for is completed. You will need to calculate that time period on your own and then when the time the customer paid is up you no longer give them access to your service.
  If your profile ID starts with S- then your EOT IPN works as follows:
  If the profile is canceled then you get an EOT at the end of the time that the buyer paid for.
  If the profile naturally ends then you get an EOT at the end of the time that the buyer paid for. If your profile ID starts with an I- Then you follow the current PayPal Rules for subscriptions. If your profile ID starts with an S- then you follow the old rules with subscriptions. You may also want to review this Doc (https://www.x.com/docs/DOC-1843) about the difference between I- and S- subscriptions.
• The subscr_eot IPN response is still fired even if the payment is not received on the last month/year/day of the subscription

You can find my detailed question & answers on the paypal forum and I hope it will be useful to you in your next project.

Your comments & questions are welcomed.