PayPal Instant Payment Notification - 2012 User Guide
Instant Payment
Notification Guide
Last updated: July 10, 2012
IPN Guide
Document Number: 10087.en_US-20120710
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 1 Introducing IPN . . . . . . . . . . . . . . . . . . . . . . . 7
IPN Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
IPN Protocol and Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
IPN Messages Generated by PayPal Payments Standard . . . . . . . . . . . . . . . 11
IPN Messages Generated by APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
IPN Messages Generated by a Back-Office Procedure . . . . . . . . . . . . . . . . . 13
PayPal-Initiated IPN Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
A Sample IPN Message and Response . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Non-IPN Notification Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2 Implementing an IPN Listener . . . . . . . . . . . . . . . .19
Chapter 3 Identifying Your IPN Listener to PayPal . . . . . . . . . . .21
Setting Up IPN Notifications on PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Dynamically Setting the Notification URL . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 4 IPN Testing . . . . . . . . . . . . . . . . . . . . . . . . . 25
Testing Your Listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
IPN Troubleshooting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 5 IPN Operations on PayPal . . . . . . . . . . . . . . . . . . 29
Using the IPN History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Resending IPN Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
July 10, 2012 3
Contents
Chapter 6 Using Fraud Management Filters With IPN . . . . . . . . . 37
Chapter 7 IPN Variable Reference . . . . . . . . . . . . . . . . . . . 41
IPN Transaction Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Transaction and Notification-Related Variables . . . . . . . . . . . . . . . . . . . . . . . 42
Buyer Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Payment Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Auction Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Mass Pay Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Recurring Payments Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Subscription Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Dispute Resolution Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Pay Message Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Preapproval Message Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Adaptive Accounts IPN Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Payment Review Using Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4 July 10, 2012
Preface
This document describes the Instant Payment Notification (IPN) message service.
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
IPN Guide July 10, 2012 5
Documentation Feedback
6 July 10, 2012 IPN Guide
1
Instant Payment Notification (IPN) is a message service that notifies you of events related to
PayPal transactions. You can use it to automate back-office and administrative functions, such
as fulfilling orders, tracking customers, and providing status and other information related to a
transaction.
IPN Overview
IPN Protocol and Architecture
A Sample IPN Message and Response
Non-IPN Notification Mechanisms
IPN Overview
IPN notifies you when an event occurs that affects a transaction. Typically, these events
represent various kinds of payments; however, the events may also represent authorizations,
Fraud Management Filter actions and other actions, such as refunds, disputes, and
chargebacks.
Introducing IPN
IPN is a message service that PayPal uses to notify you about events, such as:
Instant payments, including Express Checkout, Adaptive Payments, and direct credit card
payments, and authorizations, which indicate a sale whose payment has not yet been
collected
eCheck payments and associated status, such as pending, completed, or denied, and
payments pending for other reasons, such as those being reviewed for potential fraud
Recurring payment and subscription actions
Chargebacks, disputes, reversals, and refunds associated with a transaction
In many cases, the action that causes the event, such as a payment, occurs on your website;
however, your website is not the only source of events. In many cases, events can be generated
by Website Payment Standard buttons, the PayPal API, or by PayPal itself.
You detect and process IPN messages with a listener, sometimes called a handler, which is a
script or program that you write. It waits for messages and passes them to various back-end or
administrative processes that respond the messages. PayPal provides sample code that you can
modify to implement a listener that detects IPN messages.
The actions to take when your listener is notified of an event are specific to your needs.
Examples of the kinds of actions you might take when your listener receives an IPN message
include the following:
IPN Guide July 10, 2012 7
Introducing IPN
IPN Overview
Trigger order fulfillment or enable media downloads when a check clears or a payment is
made
Update your list of customers
Update accounting records
Create specialized “to do” lists based on the kind of event
You are typically notified of events by email as well, but the IPN message service enables you
to automate your response to events. The following diagram shows how events can occur and
how PayPal responds with IPN messages that it sends to your listener:
8 July 10, 2012 IPN Guide
Introducing IPN
IPN Protocol and Architecture
The diagram shows requests and responses, which are the result of processing button clicks or
API operations on PayPal. PayPal sends an IPN message when it sends a response to a request.
The IPN message is not actually part of the response sent to your website. Rather, the IPN
message is sent to the your listener, which allows you to take actions that are not directly tied
to the operation of your website.
NOTE: The diagram does not show the IPN authen tication protocol messages that validate the
IPN message.
IPN is an asynchronous message service, meaning that messages are not synchronized with
actions on your website. Thus, listening for an IPN message does not increase the time it takes
to complete a transaction on your website.
The IPN message service does not assume that all messages will be received by your listener
in a timely manner. Because the internet is not 100% reliable, messages can become lost or
delayed. To handle the possibility of transmission and receipt delays or failures, the IPN
message service implements a retry mechanism that resends messages at various intervals
until you acknowledge that the message has successfully been received. Messages may be
resent for up to four days after the original message.
NOTE: Unless you are certain that a failure occurred on the the Internet, the most likely cause
of lost, delayed, or duplicate IPN messages is faulty logic in the listener itself.
Because messages can be delivered at any time, your listener must always be available to
receive and process messages; however, the retry mechanism also handles the possibility that
your listener could become swamped or stop responding.
The IPN message service should not be considered a real-time service. Your checkout flow
should not wait on an IPN message before it is allowed to complete. If your website waits for
an IPN message, checkout processing may be delayed due to system load and become more
complicated because of the possibility of retries.
IPN Protocol and Architecture
IPN is designed to be secure, reliable, and asynchronous. To meet these requirements, the
protocol requires you to acknowledge receipt of IPN messages. The IPN service provides a
retry mechanism to handle cases in which a message is not acknowledged; for example, when
a transmission or receipt failure occurs.
When you enable IPN, PayPal sends messages to the IPN listener at the URL you specify in
your account’s profile. You can override the URL to associate other IPN listeners with specific
transactions. In this case, you specify the listener’s URL when you set up a Website Payment
Standard button or a PayPal API operation.
The IPN protocol consists of three steps:
1. PayPal sends your IPN listener a message that notifies you of the event
IPN Guide July 10, 2012 9
Introducing IPN
IPN Protocol and Architecture
2. Your listener sends the complete unaltered message back to PayPal; the message must
contain the same fields in the same order and be encoded in the same way as the original
message
3. PayPal sends a single word back, which is either VERIFIED if the message originated with
PayPal or INVALID if there is any discrepancy with what was originally sent
Your listener must respond to each message, whether or not you intend to do anything with it.
If you do not respond, PayPal assumes that the message was not received and res ends the
message. PayPal continues to resend the message periodically until your listener sends the
correct message back, although the interval between resent messages increases each time. The
message can be resent for up to four days.
This resend algorithm can lead to situations in which PayPal resends the IPN message while
you are sending back the original message. In this case, you should send your response again,
to cover the possibility that PayPal did not actually receive your response the first time. You
should also ensure that you do not process the transaction associated with the message twice.
IMPORTANT: PayPal expects to receive a response to an IPN message within 30 seconds.
Your listener should not perform time-consuming operations, such as creating
a process, before responding to the IPN message.
After PayPal verifies the message, there are additional checks that your listener or back-end or
administrative software must take:
Verify that you are the intended recipient of the IPN message by checking the email address
in the message; this handles a situation where another merchant could accidentally or
intentionally attempt to use your listener.
Avoid duplicate IPN messages. Check that you have not already processed the transaction
identified by the transaction ID returned in the IPN message. You may need to store
transaction IDs and the last payment status returned by IPN messages in a file or database
so that you can check for duplicates. If the transaction ID sent by PayPal is a duplicate, you
should not process it again.
NOTE: You must track the last payment status returned by IPN messages because PayPal
could send an IPN for a pending payment and a second one for the completed
payment, both of which would have the same transaction ID. Relying on just the
transaction ID could lead to the completed payment being treated as a duplicate.
Because IPN messages can be sent at various stages in a transaction’s progress, make sure
that the transaction’s payment status is “completed” before enabling shipment of
merchandise or allowing the download of digital media.
Verify that the payment amount actually matches what you intend to charge. Although not
technically an IPN issue, if you do not encrypt buttons, it is possible for someone to capture
the original transmission and change the price. Without this check, you could accept a
lesser payment than what you expected.
10 July 10, 2012 IPN Guide
IPN Protocol and Architecture
IPN Messages Generated by PayPal Payments Standard
PayPal generates an IPN message when your customer clicks a PayPal Payments Standard
(previously known as Website Payments Standard) payment button, such as a Buy Now
button, and completes the transaction on PayPal. You can use this notification to kick-off order
fulfillment, enable digital media downloads, store information in a customer relationship
management (CRM) or accounting system, and so on.
The following diagram shows both the web flow and the IPN message authentication protocol:
Introducing IPN
The numbers in diagram correspond to the following steps:
1. The button action initiates a payment that completes on PayPal
2. PayPal sends your IPN listener a message that notifies you of the event
3. Your listener sends the complete unaltered message back to PayPal; the message must
contain the same fields in the same order and be encoded in the same way as the original
message
4. PayPal sends a single word back, which is either VERIFIED if the message originated with
PayPal or INVALID if there is any discrepancy with what was originally sent
Your IPN listener must implement the IPN authentication protocol (steps 2, 3, and 4 in this
diagram). After successfully completing the protocol, your back-office or administrative
process vets the contents of the message and responds appropriately. For example, if the
payment status for the transaction is “Completed,” your system can print a packing list or
email a password to your customer for downloading digital media.
IPN Guide July 10, 2012 11
Introducing IPN
IPN Protocol and Architecture
IPN Messages Generated by APIs
PayPal generates an IPN message when you invoke an API operation, such as
DoExpressCheckoutPayment of DoDirectPayment during checkout or an Adaptive
Payments Pay, Preapproval, or ExecutePayment API operation. You can use this
notification to kick-off order fulfillment, enable digital media downloads, store information in
a customer relationship management (CRM) or accounting system, and so on.
The following diagram shows both the web flow and the IPN message authentication protocol:
The numbers in the diagram correspond to the following steps:
1. The API operation initiates a payment on PayPal.
2. PayPal sends your IPN listener a message that notifies you of the event
3. Your listener sends the complete unaltered message back to PayPal; the message must
contain the same fields in the same order and be encoded in the same way as the original
message
4. PayPal sends a single word back, which is either VERIFIED if the message originated with
PayPal or INVALID if there is any discrepancy with what was originally sent
Your IPN listener must implement the IPN authentication protocol (steps 2, 3, and 4 in this
diagram). After successfully completing the protocol, your back-office or administrative
process vets the contents of the message and responds appropriately. For example, if the
payment status for the transaction is “Completed,” your system can print a packing list or
email a password to your customer for downloading digital media.
12 July 10, 2012 IPN Guide
IPN Messages Generated by a Back-Office Procedure
PayPal generates an IPN message when you perform actions that invoke the PayPal API,
regardless of whether it is from your website or from a back-office or administrative
procedure. You can use this notification to trigger an email to your customer, store information
in a CRM or accounting system, and so on.
The following diagram shows both an administrative web flow and the IPN message
authentication protocol:
Introducing IPN
IPN Protocol and Architecture
The numbers in diagram correspond to the following steps:
1. Your back-office or administrative process invokes a PayPal API operation; for example, it
could invoke the RefundTransaction API operation when your employee issues a
refund.
2. PayPal sends your IPN listener a message that notifies you of the event
3. Your listener sends the complete unaltered message back to PayPal; the message must
contain the same fields in the same order and be encoded in the same way as the original
message
4. PayPal sends a single word back, which is either VERIFIED if the message originated with
PayPal or INVALID if there is any discrepancy with what was originally sent
Your IPN listener implements the IPN authentication protocol (steps 2, 3, and 4 in this
diagram). After successfully completing the protocol, your listener or back-office or
administrative process vets the contents of the message and responds appropriately. For
example, your system can notify the customer of the refund by email.
IPN Guide July 10, 2012 13
Introducing IPN
A Sample IPN Message and Response
PayPal-Initiated IPN Messages
Some IPN messages generated by PayPal are not directly associated with a web flow. PayPal
generates an IPN message when external events arise that might affect a transaction, such as
disputes, chargebacks, echeck clearing, and various recurring payment and subscription
events.
In this case, events that trigger IPN messages are not directly related to actions on your
website. The following diagram shows the steps your listener must take:
The numbers in diagram correspond to the following steps, which implement the IPN message
authentication protocol:
1. PayPal sends your IPN listener a message that notifies you of the event
2. Your listener sends the complete unaltered message back to PayPal; the message must
contain the same fields in the same order and be encoded in the same way as the original
message
3. PayPal sends a single word back, which is either VERIFIED if the message originated with
PayPal or INVALID if there is any discrepancy with what was originally sent
After successfully completing the protocol, your back-office or administrative process vets the
contents of the message and responds appropriately. For example, the IPN messages may
trigger you to print shipping labels for items whose payments have cleared, investigate
disputes and chargebacks, store information in an accounting system, and so on.
A Sample IPN Message and Response
An IPN message consists of variables that describe the transaction. These variables contain
information about you, your customer, and the details of the transaction itself.
PayPal sends a message, similar to the following one, for a $19.95 purchase made by Express
Checkout:
14 July 10, 2012 IPN Guide
Introducing IPN
A Sample IPN Message and Response
mc_gross=19.95&protection_eligibility=Eligible&address_status=confirmed&pay
er_id=LPLWNMTBWMFAY&tax=0.00&address_street=1+Main+St&payment_date=20%3A12%
3A59+Jan+13%2C+2009+PST&payment_status=Completed&charset=windows1252&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&add
ress_country=United+States&address_city=San+Jose&quantity=1&verify_sign=Atk
OfCXbDm2hu0ZELryHFjY-Vb7PAUvS6nMXgysbElEn9v1XcmSoGtf&payer_email=gpmac_1231902590_per%40paypal.com&txn_id=61E67681CH32
38416&payment_type=instant&last_name=User&address_state=CA&receiver_email=g
pmac_1231902686_biz%40paypal.com&payment_fee=0.88&receiver_id=S8XGHLYDW9T3S
&txn_type=express_checkout&item_name=&mc_currency=USD&item_number=&residenc
e_country=US&test_ipn=1&handling_amount=0.00&transaction_subject=&payment_g
ross=19.95&shipping=0.00
Variable Notes
Information about you:
receiver_email = gm_1231902686_biz@paypal.com Check email address to make sure that this is not a spoof
receiver_id = S8XGHLYDW9T3S
residence_country = US
Information about the transaction:
test_ipn = 1 Testing with the Sandbox
transaction_subject =
txn_id = 61E67681CH3238416 Keep this ID to avoid processing the transaction twice
txn_type = express_checkout Type of transaction
Information about your buyer:
payer_email = gm_1231902590_per@paypal.com
payer_id = LPLWNMTBWMFAY
payer_status = verified
first_name = T est
last_name = User
address_city = San Jose
address_country = United States
address_country_code = US
address_name = Test User
address_state = CA
address_status = confirmed
IPN Guide July 10, 2012 15
Introducing IPN
A Sample IPN Message and Response
Variable Notes
address_street = 1 Main St
address_zip = 95131
Information about the payment:
custom = Your custom field
handling_amount = 0.00
item_name =
item_number =
mc_currency = USD
mc_fee = 0.88
mc_gross = 19.95
payment_date = 20:12:59 Jan 13, 2009 PST
payment_fee = 0.88
payment_gross = 19.95
payment_status = Completed Status, which determines whether the transaction is
complete
payment_type = instant Kind of payment
protection_eligibility = Eligible
quantity = 1
shipping = 0.00
tax = 0.00
Other information about the transaction:
notify_version = 2.6 IPN version; can be ignored
charset = windows-1252
verify_sign = AtkOfCXbDm2hu0ZELryHFjY-
Vb7PAUvS6nMXgysbElEn9v-1XcmSoGtf
Before you can trust the contents of the message, you must first verify that the message came
from PayPal. To verify the message, you must send back the contents in the exact order they
were received and precede it with the command _notify-validate, as follows:
https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_notifyvalidate&mc_gross=19.95&protection_eligibility=Eligible&address_status=conf
irmed&payer_id=LPLWNMTBWMFAY&tax=0.00&...&payment_gross=19.95&shipping=0.00
16 July 10, 2012 IPN Guide
PayPal will then send one single-word message, VERIFIED, if the message is valid; otherwise,
it will send another single-word message, INVALID.
IMPORTANT: After you receive the VERIFIED message, there are several important checks
you must perform before you can assume that the message is legitimate and
not already processed:
Non-IPN Notification Mechanisms
You can use IPN with other notification mechanisms. For example, you can use PDT or the
API to determine real-time information about a transaction and let IPN notify you of any
changes after the transaction occurs.
Introducing IPN
Non-IPN Notification Mechanisms
If you are using PayPal Payments Standard, you can use PDT to obtain information about the
transaction. If you are using Express Checkout or Direct Payment, the PayPal API notifies you
of the status and details of the transaction immediately and automatically. In either case, you
can immediately display to your customer the information being returned from PayPal. You
should not use IPN for this purpose.
IPN Guide July 10, 2012 17
Introducing IPN
Non-IPN Notification Mechanisms
18 July 10, 2012 IPN Guide
2
Implementing an IPN Listener
You write your IPN listener in the scripting or programming language of your choice and host
it on your web server. You can use sample code provided by PayPal as a starting point.
The PayPal SDKs for PayPal Payments Standard contain sample code in various programming
languages that you can modify to create your own listener. As a good programming practice,
as well as to keep things simple, your IPN listener should listen for a post from PayPal and
dispatch it immediately to another routine or process that handles the business logic associated
with the message. If your listener is structured in this way, it will be a simple and tight loop
that listens for a message and dispatches it for processing by your application logic.
For a list of code samples for IPN, refer to the following link:
Code Samples - Instant Payment Notification
IPN Guide July 10, 2012 19
Implementing an IPN Listener
20 July 10, 2012 IPN Guide
Identifying Your IPN Listener to
3
PayPal
After you implement and test your IPN listener, you make your listener known to PayPal by
specifying the listener’s URL in your account’s pro file. Optio nally, you can override the URL
to specify another listener for specific payments.
Setting Up IPN Notifications on PayPal
Dynamically Setting the Notification URL
Setting Up IPN Notifications on PayPal
After you implement and test your IPN listener, you identify the listener to PayPal by selecting
Instant Payment Notification Preferences from your account’s profile. You then specify
your listener’s URL and click the box to activate it.
Your listener must be located at the URL that you specify in the profile. Before you activate
your listener on PayPal, you should test the listener using the IPN simulator in the Sandbox.
IMPORTANT:
The steps to set up your listener for Sandbox testing and to set up your listener for live
operation on PayPal are the same. The only difference is that you log into the Sandbox to set
up your listener for Sandbox testing and you log into PayPal to set up your listener for live
operation.
NOTE: Sandbox testing goes beyond simply using the IPN simulator. The IPN simulator only
sends IPN messages to a listener; it does not perform the complete operation; for
example, it does not complete a transaction. Sandbox testing involves performing the
same actions in the Sandbox as you expect to be performed when the listener goes
live.
After you log in, follow these instructions to set up your listener:
1. Click Profile on the My Account tab.
2. Click Instant Payment Notification Preferences in the Selling Preferences column.
3. Click Choose IPN Settings to specify your listener’s URL and activate the listener.
The following screen appears:
IPN Guide July 10, 2012 21
Loading...