PayPal Recurring Payment and IPN Variables

On March 16, 2014, in Other Online Technology, by James Liu

This week, I am working on one website project with PayPal Recurring Payment. As the project requirement, I need to use PayPal IPN to track all PayPal transaction. After a few research, I am so surprised that there is not a clear development document to describe the whole flow of PayPal Recurring IPN. It is necessary to write it down about what I have understand. I hope it will be helpful for developers who have the same needs.

Setup Instant payment notifications

First of all, to make the PayPal IPN working, you need to configure the IPN in PayPal selling tools area. The full name of IPN is Instant payment notifications. Here are the steps to setup PayPal IPN. (As PayPal document description, we can also dynamically setup IPN listener url in payment request by notify_url).

  • Login to your PayPal account at www.paypal.com
  • Go to Profile -> Selling Tools, find “Instant Payment Notification” and click “update”
  • Click “Choose IPN Settings” to setup your PayPal IPN
  • Fill in your notification url
  • enable PayPal IPN by selecting “Receive IPN messages (Enabled)”

IPN Setting Up

PayPal Recurring Payment IPN Parameters

Now let’s talk about PayPal IPN for Recurring payment. To implement subscription with PayPal recurring payment, we have to handle several different type of PayPal IPN.

  • subscr_signup: a subscription sign-up
  • subscr_cancel: a subscription cancellation
  • subscr_modify: a subscription modification
  • subscr_failed: subscription payment failure
  • subscr_payment: a subscription payment
  • subscr_eot: a subscription’s end of term which means subscription expired

In the ideal one time subscription, we only need to deal with 3 basic PayPal IPN calling for one subscription, the subscr_signup, subscr_payment and subscr_eot. Here are all these three IPN FORM POST looks like:

//subscr_signup
    [amount3] => 9.90
    [address_status] => confirmed
    [subscr_date] => 01:30:23 Mar 15, 2014 PDT
    [payer_id] => ZB9VSG2VCXMN8
    [address_street] => 1 Main St
    [mc_amount3] => 9.90
    [charset] => windows-1252
    [address_zip] => 95131
    [first_name] => James
    [reattempt] => 1
    [address_country_code] => US
    [address_name] => James L
    [notify_version] => 3.7
    [subscr_id] => I-E0S0VABCBGFA
    [custom] => 294-
    [payer_status] => verified
    [business] => james.sales2@gmail.com
    [address_country] => United States
    [address_city] => San Jose
    [verify_sign] => AXQYg8MSb9.A1F3eCWC2veQ7Ps5HAHOdoJIiNVVJcnIjZLB-hD3zSxhy
    [payer_email] => james.liu128@outlook.com
    [last_name] => L
    [address_state] => CA
    [receiver_email] => james.sales2@gmail.com
    [recurring] => 0
    [txn_type] => subscr_signup
    [item_name] => 1 month plan
    [mc_currency] => USD
    [item_number] => 1
    [residence_country] => US
    [test_ipn] => 1
    [period3] => 1 M
    [ipn_track_id] => 8301d90f10814
//payment complete
    [mc_gross] => 9.90
    [protection_eligibility] => Eligible
    [address_status] => confirmed
    [payer_id] => ZB9VSG2VCXMN8
    [address_street] => 1 Main St
    [payment_date] => 01:30:24 Mar 15, 2014 PDT
    [payment_status] => Completed
    [charset] => windows-1252
    [address_zip] => 95131
    [first_name] => James
    [mc_fee] => 0.59
    [address_country_code] => US
    [address_name] => James L
    [notify_version] => 3.7
    [subscr_id] => I-E0S0VABCBGFA
    [custom] => 294-
    [payer_status] => verified
    [business] => james.sales2@gmail.com
    [address_country] => United States
    [address_city] => San Jose
    [verify_sign] => AKS-BhNOdYgzPFpKl2ju9bTgsirSA2m5qKDc9NDtzIuCkq-nNPi47efZ
    [payer_email] => james.liu128@outlook.com
    [txn_id] => 4FX01730PS634781R
    [payment_type] => instant
    [last_name] => L
    [address_state] => CA
    [receiver_email] => james.sales2@gmail.com
    [payment_fee] => 0.59
    [receiver_id] => PTUTQZMYS8ZB6
    [txn_type] => subscr_payment
    [item_name] => 1 month plan
    [mc_currency] => USD
    [item_number] => 1
    [residence_country] => US
    [test_ipn] => 1
    [transaction_subject] => 1 month plan
    [payment_gross] => 9.90
    [ipn_track_id] => 8301d90f10814
//subscr_eot
    [txn_type] => subscr_eot
    [subscr_id] => I-E0S0VABCBGFA
    [last_name] => L
    [residence_country] => US
    [item_name] => 1 month plan
    [mc_currency] => USD
    [business] => james.sales2@gmail.com
    [verify_sign] => AC502yyIIcYYlZGRtufg4dzoXU78AJhDWpzBQdAIqqSCoyDawKOUYkFs
    [payer_status] => verified
    [test_ipn] => 1
    [payer_email] => james.liu128@outlook.com
    [first_name] => James
    [receiver_email] => james.sales2@gmail.com
    [payer_id] => ZB9VSG2VCXMN8
    [item_number] => 1
    [custom] => 294-
    [charset] => windows-1252
    [notify_version] => 3.7
    [ipn_track_id] => 8301d90f10814

IPN Validation

After we get the IPN, we need to verify it is a valid IPN. Here are several steps to verify a valid IPN:

  • Verify the email address used as “receiver_email” in IPN parameters has been registered and confirmed in your PayPal account.
  • Append a variable-value “cmd=_notify-validate” to the POST string
  • Send new HTTP POST to PayPal to confirm IPN valid

PayPal will respond confirm post with a single word, “VERIFIED” or “INVALID” in the body of response. If we get a verified IPN, we can update our database about payer’s subscription.

Payment Status Pending and Payment Review

To protect merchant from fraud, PayPal will put the payment transaction under Payment Review and set payment transaction status as Pending. In this situation, one of PayPal’s anti-fraud specialists will review the payment to determine if it is fraudulent. In most cases, it takes only 24 hours.

The initial IPN message indicates that the payment is under review:

  • The payment_status variable is set to Pending
  • The pending_reason variable is set to PaymentReview

A subsequent IPN message indicates the resolution of the payment review:

  • If the transaction was successful and the payment was accepted, PayPal sends a notification whose payment_status variable is set to Completed.
  • If the transaction failed and the payment was rejected, PayPal sends a notification whose payment_status variable is set to Reversed.
 

2 Responses to “PayPal Recurring Payment and IPN Variables”

  1. Anonymous says:

    awesome article, paypal is not defined user friendly documentation its also screwed up my brain from last 3 days, can you please give payment redirect form example for recurring.

    –Thanks

    • James says:

      PayPal really needs to improve their documentation. About recurring payment, there are several ways. Sometime, I will use url based request. But I am usually using form to POST all parameters. Here is one very simple example from PayPal website (very hard to find):

      <form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
      <input type="hidden" name="cmd" value="_xclick-subscriptions">
      <input type="hidden" name="business" value="me@mybusiness.com">
      <input type="hidden" name="currency_code" value="USD">
      <input type="hidden" name="no_shipping" value="1">
      <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_subscribe_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
      <input type="hidden" name="a3" value="5.00">
      <input type="hidden" name="p3" value="1">
      <input type="hidden" name="t3" value="M">
      <input type="hidden" name="src" value="1">
      <input type="hidden" name="sra" value="1">
      </form>

      The above example will create a “$5.00 for 1 month” recurring payment.

Leave a Reply

WordPress Blog

WordPress Blog