Introducing IPN

Instant Payment Notification (IPN) is a message service that notifies you of events related to PayPal transactions. You can use IPN messages to automate back-office and administrative functions, such as fulfilling orders, tracking customers, and providing status and other transaction-related information.

IPN Overview

The IPN service notifies you when an event occurs that pertains to 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.

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 triggers an IPN event is a user-action on your website. However, other actions can trigger trigger IPNs. For example, your site's back-office process might invoke a PayPal API that refunds a payment, or a customer might notify PayPal of a disputed charge.

You receive and process IPN messages with a listener (sometimes called a handler), which is a program that you write. This program waits for IPNs and (typically) passes them to an administrative process that responds appropriately. PayPal provides sample code that you can modify to implement a listener that handles IPN messages.

The action to take when your listener is notified of an event are application-specific. Here are some common actions applications take in response to IPN messages:

  • Trigger order fulfillment or enable media downloads
  • Update a list of customers
  • Update accounting records
  • Create specialized "to do" lists

In addition to IPN messages, you are notified of events by email. However, unlike email, IPN messages let you automate responses to events. The diagram below shows various events that can occur and how PayPal responds by sending IPN messages to your listener.

The diagram shows requests and responses, which are the result of processing button clicks or API operations at PayPal. PayPal sends an IPN message when it sends a response to a request. However, the IPN message is not actually part of the response sent to your website. Rather, the IPN message is sent to the your listener. his feature lets you take actions that are not directly tied to the operation of your website.

Note The diagram does not show the IPN authentication protocol that a listener must implement to validate an IPN message. This protocol is discussed in detail below.

IPN is an asynchronous message service, meaning that IPNs are not synchronized with actions on your website. Thus, listening for an IPN message does not increase the time required to complete a transaction on your website.

The IPN message service does not assume that your listener will receive all IPN messages. Because the Internet is not 100% reliable, IPNs can get lost or be delayed. To address these issues, the IPN message service includes a retry mechanism that re-sends a message at various intervals until your listener acknowledges receipt. An IPN message may be resent up to four days after the original was sent. The maximum number of retries is 15.

Note Although the Internet may be at fault, the most likely cause of lost, delayed, or duplicate IPN messages is faulty logic in the listener itself.

Because IPN messages can arrive at any time, your listener should always be available; however, the IPN retry mechanism handles the case in which your listener is down temporarily.

The IPN message service is not a real-time service. As a result, your listener may not receive an IPN message for many seconds after an event occurs. As a result, your checkout flow should not depend upon receiving an IPN message to complete. If it does, your checkout flow will be slow during periods of heavy system load and complicated, since it must handle retries.

IPN Protocol and Architecture

The IPN message service is designed to be secure, reliable, and asynchronous. To meet these requirements, the protocol requires that you acknowledge receipt of IPN messages. The IPN service provides a retry mechanism to handle cases in which a message is not acknowledged, e.g., when a transmit or receive failure occurs.

If you enable the IPN service, PayPal sends messages to the IPN listener at the URL you specify in your account profile. If you want, you can override this URL in order to associate a different IPN listener with a specific transaction. To do this, you can either:

  • Specify the URL of a different listener in your definition of a PayPal Payment Standard button
    or
  • Pass the URL of a different listener to a call of a PayPal API operation

The IPN message authentication protocol consists of four steps:

  1. PayPal HTTP POSTs your listener an IPN message that notifies you of an event.
  2. Your listener returns an empty HTTP 200 response to PayPal.
  3. Your listener HTTP POSTs the complete, unaltered message back to PayPal; the message must contain the same fields (in the same order) as the original message and be encoded in the same way as the original message.
  4. PayPal sends a single word back - either VERIFIED (if the message matches the original) or INVALID (if the message does not match the original).

Your listener must respond to every IPN message it gets, whether you take action on it or not. If you do not respond, PayPal assumes the IPN was not received and re-sends it. Further, PayPal continues to re-send the message periodically until your listener responds, although the interval between retries increases with each attempt. An IPN will be resent for up to four days, with a maximum of 15 retries.

This resend algorithm can lead to situations in which PayPal re-sends an IPN message at the same time you are sending back the original message. In this case, you should send your response again, to address the possibility that PayPal did not receive your first response. You must also ensure that you do not process the transaction associated with an IPN message twice.

Important

  • Every IPN message you receive from PayPal includes a User-Agent HTTP request header whose value is PayPal IPN ( https://www.paypal.com/ipn ). Do not use this header to verify that an IPN really came from PayPal and has not been tampered with. Rather, to verify these things, you must use the IPN authentication protocol outlined above.
  • PayPal expects to receive a response to an IPN message within 30 seconds. Consequently, your listener must not perform time-consuming operations (such as updating a database) before responding to an IPN.

After PayPal verifies an IPN, your listener or administrative software should make these additional checks:

  • Verify that you are the intended recipient of the IPN message.
    To do this, check the email address in the message. This check prevents another merchant from accidentally or intentionally using your listener.
  • Verify that the IPN is not a duplicate.
    To do this, save the transaction ID and last payment status in each IPN message in a database and verify that the current IPN's values for these fields are not already in this database.

    Note You can't rely on transaction ID alone to screen out duplicates, as this scenario shows: 1) PayPal sends you an IPN notifying you of a pending payment. 2) PayPal later sends you a second IPN telling you that the payment has completed. However, both IPNs contain the same transaction ID; therefore, if you were using just transaction ID to identify IPNs, you would to treat the "completed payment" IPN as a duplicate.

  • Ensure that you receive an IPN whose payment status is "completed" before shipping merchandise or enabling download of digital goods.
    Because IPN messages can be sent at various stages in a transaction's progress, you must wait for the IPN whose status is "completed' before handing over merchandise to a customer.
  • Verify that the payment amount in an IPN matches the price you intend to charge.
    If you do not encrypt your button code, it's possible for someone to capture a button-click message and change the price it contains. If you don't check the price in an IPN against the real price, you could accept a lower payment than you want.

IPN Message Generation and Flow

PayPal sends your listener an IPN message when any of these things happens:

  • A user on your website clicks a PayPal Payments Standard payment button (e.g., a Buy Now button) and completes payment on PayPal's site.
  • A user on your website clicks a PayPal payment button, causing your web application to invoke either an Express Checkout API (such as DoExpressCheckoutPayment) or an Adaptive Payments API (such as Pay, Preapproval, or ExecutePayment) that completes the payment on your site.
  • A user on your website clicks your own payment button, causing your web application to call a Direct Payment API operation (such as DoDirectPayment) that completes the payment on your site.
  • Your back-office application invokes a PayPal API operation, such as RefundTransaction.
  • PayPal observes an external event, such as a dispute, chargeback, an eCheck clearing, or various recurring payment and subscription events.

In the first two cases, your customer is redirected from your web app to PayPal for some or all steps of the transaction. When the user completes payment, PayPal sends an asynchronous IPN message to your listener.

In the third case, your customer is not redirected to PayPal; instead, the user enters all payment information on your site. Again, when the user completes payment, PayPal sends an asynchronous IPN message to your listener.

In the last two cases, IPN messaging is initiated by either your back-office process or by PayPal itself (as opposed to an end-user). The IPN message is still sent asynchronously, but there is no web flow involved.

No matter what causes PayPal to send an IPN message, your site can use such messages to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on. However, before you do any of these things, you must be certain that the IPN has not been tampered with. To do this, your listener must implement the IPN authentication protocol. Steps 2, 3, 4, and 5 in the diagram below show this protocol.

The numbers in the diagram correspond to the following actions:

  1. A user clicks a PayPal button to kick off a checkout flow; your web application makes an API call; your back-office system makes an API call; or PayPal observes an event.
  2. PayPal HTTP POSTs your listener an IPN message that notifies you of this event.
  3. Your listener returns an empty HTTP 200 response.
  4. Your listener HTTP POSTs the complete, unaltered message back to PayPal.

    Note This message must contain the same fields, in the same order, as the original IPN from PayPal, all preceded by cmd=_notify-validate. Further, this message must use the same encoding as the original.

  5. PayPal sends a single word back - either VERIFIED (if the message matches the original) or INVALID (if the message does not match the original).

Remember To prevent fraud, your IPN listener must implement the IPN authentication protocol (steps 2, 3, 4, and 5 in the diagram above). Upon receipt of a VERIFIED response, your back-office process can parse the contents of the IPN message and respond appropriately - print a packing list, enable a digital download, etc.

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:

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&notify_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

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 = Test
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
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.paypal.com/cgi-bin/webscr?cmd=_notify-validate&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&notify_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

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 have authenticated an IPN message (that is, received a VERIFIED response from PayPal), you must perform these important checks before you can assume that the IPN is both legitimate and has not already been processed:

  1. Check that the payment_status is Completed.
  2. If the payment_status is Completed, check the txn_id against the previous PayPal transaction that you processed to ensure the IPN message is not a duplicate.
  3. Check that the receiver_email is an email address registered in your PayPal account.
  4. Check that the price (carried in mc_gross) and the currency (carried in mc_currency) are correct for the item (carried in item_name or item_number).

Once you have completed these checks, IPN authentication is complete. Now, you can update your database with the information provided and initiate any back-end processing that's appropriate.

Non-IPN Notification Mechanisms

You can use IPN with other notification mechanisms. For example, you can use PDT or the API to obtain real-time information about a transaction and let IPN notify you of any changes after the transaction occurs.

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 show your customer the payment information returned by PayPal . You should not use IPN for this purpose.