Paypal IPN
Instant Payment Notification is better known as Paypal IPN and is Paypal’s interface for handling real time confirmation of purchases.
A typical use for IPN is where you want a customer to pay for a software download but there can be more to it than that and the IPN interface provides a wealth of options some of which I will go through in this article.
See my new Video Tutorial for Linklok. Videos make things much easier to understand.
Paypal have a simple demo of the basics of a Paypal IPN purchase, plus a good explanation called Introducing IPN and I have a more in depth Paypal IPN Tutorial available on this site which includes example php code. You should view these explanations before reading on but a very simple summary goes as follows:
- Customer clicks the buy button and makes the payment through Paypal
- Paypal posts a notification to your server with all the payment details
- Your server echoes back the details
- Paypal authenticates the transaction and sends VERIFIED or INVALID response
- When your server sees VERIFIED it makes some checks and processes the order
The best place to search for information is the Paypal Integration centre. which has guides, code and links for everything to do with integrating your website with Paypal. It covers much more than just IPN. This article will assume you have decided that IPN is right for you.
The one place you MUST visit is the Paypal IPN Forum on the developer website. As well as a constantly changing list of discussion topics about IPN, there are some good sticky posts about troubleshooting tips, IPN variables, template code etc.
Paypal Sandbox
When you are developing your website you really don’t want to be trying to get it working by experimenting on a real money system. Any early bugs in the system could leave security holes but even if you write perfect code it is best not to do your testing using real money.
Paypal provides what they call a sandbox, almost identical to the live Paypal system. You can setup fake customers with fake money and make as many test purchases as you want. The perfect system to fully test your web application.
The Sandbox sets the variable test_ipn with a value of 1 in the HTTP response back to your IPN page. You may want to check for this so you know you are dealing with the real or the sandbox system.
There is a Testing Forum on the developer network. It’s a great place for advice.
Paypal Account
Paypal provide 3 different types of account. Personal, Premier and Business. You will need Premier or Business to use IPN.
Paypal IPN Events
IPN messages are normally generated to indicate a payment has occurred but this is not the only situation and you should be prepared to handle all of the following situations.
- Instant payments, including Express Checkout and direct credit card payments
- eCheck payments and associated status, such as pending, completed, or denied
- Payments that may be pending for other reasons, such as those being reviewed for potential fraud
- Events related to recurring payments and subscriptions
- Authorizations, which indicate a sale whose payment has not yet been collected
- Chargebacks, which are initiated by a credit card processor; for example, when a customer disputes a charge
- Disputes, which are initiated by a buyer using the PayPal resolution process
- Reversals, which occur when you win a dispute or a chargeback is canceled
- Refunds, which you may choose to give
Listener
Paypal IPN messages are not synchronized with actions on your website. You detect IPN messages from Paypal with a piece of code known as a listener. Paypal provides example code and there is also an example IPN code snippet in the IPN tutorial.
You specify the URL of your listener in your Paypal account’s profile (Profile, Selling Preferences, Instant Payment Notification Preferences) but you can override this for specific transactions when you setup a button or API operation (Set the notify_url HTML form variable). You can also temporarily turn off the sending of IPN messages, useful if your site is down for maintenance. They are still generated and stored until you switch sending back on again.
Paypal expects an acknowledgement from you (within 30secs) to show you have received the IPN message ok. If you don’t send an acknowledgement Paypal will resend the IPN message at intervals for up to 4 days after the first message. So even if you don’t intend to process the message you must acknowledge it or Paypal will send it again. If you receive a re transmission from Paypal even though you sent an acknowledgement you should send another acknowledgement. There may be a timing problem or the first acknowledgement may have been lost. Your listener code must be able to cope with this retry situation without processing the transaction twice.
Paypal recommends that your checkout flow should NOT wait for an IPN message before it is allowed to complete.
Listener Processing
You must perform a number of checks on the IPN message received from Paypal.
- Check the email address to make sure it is yours
- Check that you have not already processed the transaction identified by the transaction ID
- Make sure that the transaction’s payment status is “completed”
- Verify that the payment amount actually matches what you intend to charge
Example IPN Message
A typical IPN message:
mc_gross=19.95&protection_eligibility=Eligible&address_status=confirmed&payer_id=LPLWNMTBWMFAY&tax=0.00&address_street=1+Main+St&payment_date=20%3A12%3A59+Jan+13%2C+2009+PST&payment_status=Completed&charset=windows-1252&address_zip=95131&first_name=Test&mc_fee=0.88&address_country_code=US&address_name=Test+User¬ify_version=2.6&custom=&payer_status=verified&address_country=United+States&address_city=San+Jose&quantity=1&verify_sign=AtkOfCXbDm2hu0ZELryHFjY-Vb7PAUvS6nMXgysbElEn9v-1XcmSoGtf&payer_email=gpmac_1231902590_per%40paypal.com&txn_id=61E67681CH3238416&payment_type=instant&last_name=User&address_state=CA&receiver_email=gpmac_1231902686_biz%40paypal.com&payment_fee=0.88&receiver_id=S8XGHLYDW9T3S&txn_type=express_checkout&item_name=&mc_currency=USD&item_number=&residence_country=US&test_ipn=1&handling_amount=0.00&transaction_subject=&payment_gross=19.95&shipping=0.00
Testing your Listener
The Sandbox has an excellent IPN Simulator (under Test Tools) which lets you choose the transaction type, fill in all the parameter values and send a test IPN to a specified address.
Some advice on the forum about using curl/fsockopen/local testing.
When things go wrong…
If you receive nothing at all.
- check that you have specified not only the correct file name for your IPN listener but also the correct path to the file.
- Check your firewall isn’t blocking HTTP POST messages from PayPal.
- Check the webserver logs for any errors
If you receive some messages but not all.
- Make sure the listener is processing ALL messages
- Make sure account is valid and confirmed
If you receive INVALID message.
- Check you are sending your responses to the correct paypal address
- Verify that your response contains exactly the same IPN variables and values in the same order, preceded with cmd=_notify-validate.
- Ensure that you are encoding your response string and are using the same character encoding as the original message.
IPN History
Paypal provides an IPN history page under the My Account tab. Click on History to see it. It includes everything you want to know about each IPN message including the following Status values.
- Sent: indicates that PayPal sent the message to your IPN listener
- Failed: indicates that PayPal did not receive an acknowledgement to the message
- Queued: indicates that PayPal is ready to send the message
- Retrying: indicates that message was resent between 1 and 15 times and PayPal continues to be resend the message
- Disabled: indicates that the message will not be resent because the merchant’s account has been disabled
IPN Resending
Use the History page to resend an IPN.
Conclusion
Paypal IPN is a difficult subject but the combination of an excellent testing environment in the form of the sandbox and the good quality advice provided through the forums should make it possible for you to get your website application up and running.
Interesting External Blogs
-
Process Paypal IPN Requests Through WordPress « James Van Dyne – Process Paypal IPN Requests Through WordPress. Introduction. Paypal is perhaps the easiest way to send/receive money online and WordPress is perhaps the most popular blogging platform out there. Wouldn’t it be great if there was a way …
-
PayPal IPN Python Code | Django Aware – PayPal has Instant Payment Notification (IPN) libraries with examples for Perl, Java, and even Ruby, but look as hard as I may none for Python. Then again I.
I’ve made a tutorial at
http://learnbysoft.blogspot.com/2010/09/paypal-ipn-google-app-engine-python.html
It is for PayPal IPN and Google App Engine(python).
my ipn history in paypal show all ipn in retrying mode rather than sent..
any suggestions to fix this problem…its preventing emails from being sent to purchaser.
IN SANDBOX ENVIRONNEMENT : from my ipn history Why in the instant payment Notification(IPN) details I show HTTPresponse code 200 although I did not post the request to paypal sandbox from my IPN LISTNER SCRIPT as follow :
script php :
$value)
{
$value = urlencode(stripslashes($value));
$req .= “&” . $key . “=” . $value;
$monfichier = fopen(‘compteur.txt’, ‘r+’);
fputs($monfichier , $req . ‘ ‘ );
fclose($monfichier);
}
?>
Sorry Eleuch I don’t know.
Paypal might be doing retries if it doesn’t see a 200 from you.
Checking your server logs would be useful
Thanks for your great article.
I’m wondering if you could give me some ideas on IPN issue.
With the IPN on subscription (recurring every month),
will the IPN be called every time when recurring event is triggered each month?
If so, how can I not call the IPN on the recurring event?
I only want to call the IPN first time when they pay.
Any ideas would be very appreciated!
Thanks a lot in advance!
Hi Ryan,
There is a good explanation here that might help you.
http://www.mixedwaves.com/2010/11/paypal-subscriptions-ipn-demystified/
I think you have to understand that Paypal will always send the IPN but you can choose to ignore it by looking at the value of txn_type. If it is subscr_payment for example you could just do nothing.
Cheers
Mike
Thank you for this article and the link to Linklok – I think this is exactly what I was looking for!!