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 2011If 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.

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.
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 IDs start 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.

  • Roman

    Penuel, there have been changes about that. Take a look at https://www.x.com/message/201107#201107 (post #27).

  • http://www.codetoon.com Penuel

    Roman, thanks for the update and posting it here. Does that mean EOT will be sent even if the subscription is cancelled by the customer? That can make things simpler. Have you tested this?

  • Roman

    I’d expect things to be so, but I am only researching this and haven’t tested. You could ask your question on the forum yourself.

  • http://www.codetoon.com Penuel

    Today I received a subscr_eot IPN response for an account that was cancelled by the customer one month ago for her monthly plan. This confirms that subscr_eot IPN is now sent when the term actually ends even if the customer cancelled the subscription.

  • http://www.plrsifu.com plr store

    Hi, do you have a working IPN script for paypal subscriptions?

  • http://www.codetoon.com Penuel

    Yes I can provide the necessary scripts with any kind of customizations. If you are interested you may contact me at penuel(at)codetoon(dot)com

  • dan

    Can you post the fields that PayPal will send back to site when one subscr_payment is sent?

  • http://www.codetoon.com Penuel

    Hi Dan,

    I am not sure about it right now, as i will have to test it actual conditions and see but the Paypal Docs are good reference of what you get in IPN responses. Also during the first payment you will get two IPN responses subscr_payment & subscr_signup in an short intervals.

  • Nisha

    Very helpful post thank you 🙂 Good job.

  • http://www.codetoon.com Penuel

    Thanks 🙂

  • Neeraj

    Thanks for the insightful article.

    Question for you: what transaction type is sent when all N payment retries fail?

  • http://www.codetoon.com Penuel

    Hi Neeraj, thanks for your comments. Regarding your question I am sorry I haven’t looked at paypal IPNs much since I wrote the article so can’t correctly answer your question, but Paypal docs/forums can be a good reference. Currently I use recurly to manage recurring/subscription payments.

  • http://strategypartners.co Gerardo Ritchey

    The message that gets sent after all recurring payments fail is:

    recurring_payment_suspended_due_to_max_failed_payment

  • http://www.justiworld.com N Singh

    Is there any way …we can charge from paypal based on profile profile id?

  • Lisa Backer

    Thank you for the great article. I understand that it’s been some time but I was wondering if you know where PayPal indicates that a merchant canceling a recurring payment will not generate a subscr_eot notification?

  • Josh MacDonald

    You have 2: subscr_eot bullets, each explaining something different.

  • Eric Resnick

    Our database IPN handler system acts upon subscr_eot IPNs with both the S- and the I- prefixes. The EOT is ALWAYS sent, for both, after a canceled subscription reaches its final paid-up date. It is sent at the precise end of the paid up period. It is NEVER required that one calculate the paid up period.

    I don’t know why there is so much contradiction in this post, or why it is so popular in Google search, it is confusing and quite mistaken, even when taking into consideration the updates near the bottom.