Chapter 6. Instant Payment Notifications (IPNs)

Instant Payment Notifications (IPNs) are messages that PayPal sends you regarding a transaction status and can serve a variety of useful purposes. This brief chapter introduces IPNs, covers some of the common use cases for when IPNs can be helpful, and ultimately, teaches you how to use them to perform a follow-up action after a purchase as part of a Tweet Relevance integration.

Note

PayPal’s official documentation on IPNs is available online: Instant Payment Notification Guide.

Overview of IPNs

IPNs notify you when an event occurs that affects a transaction. Typically, these events represent various kinds of payments but could also represent authorizations, Fraud Management Filter actions, refunds, disputes, chargebacks, the status of an eCheck payment, etc. More specifically, IPNs are commonly employed regarding:

• 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

Note

See Instant Payments versus eChecks for a brief overview of eChecks versus instant payments.

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 (not covered in this book) or various PayPal APIs such as DoExpressCheckoutPayment. You can detect and process IPN messages with a listener script that waits for messages and passes them to various backend or administrative processes that respond to them. 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:

• Trigger order fulfillment or enable media downloads when an eCheck clears or a payment is made

• Update your list of customers

• Update accounting records

• Send follow-up emails regarding the transaction

You are typically notified of events by email as well, but the IPN message service enables you to automate a response to events using a well-formed API. Additionally, IPNs are asynchronous, which means 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 an algorithm that resends messages at various intervals until you acknowledge that the message has successfully been received. The delay between each successive resend attempt increases, and the IPN message service will retry for up to four days after the original message attempt.

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, and 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 even 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 merchant account’s profile, although 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 PayPal API operation. The IPN protocol consists of three steps:

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, prepended with the request parameters cmd=_notify-validate.

3. PayPal sends a single word back, VERIFIED or INVALID, indicating whether or not the IPN originated with PayPal.

Your listener must respond to each message, whether or not you intend to do anything with it, because PayPal assumes that the message was not received and resends the message for up to four days if you do not respond. The resend algorithm increases the interval between each successive retry, which can lead to an interesting edge case: PayPal may resend 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, which is usually handled by persisting all transaction IDs that you have processed.

Once PayPal verifies the IPN, there are additional checks that your listener should take before it performs any follow-up actions:

• 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. It’s an unlikely but possible circumstance that you should be prepared to handle.

• 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 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.

• 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. For example, eCheck statuses may initially be “pending” and potentially even end up resulting in a “denied” status.

• Verify that the payment amount actually matches what you intend to charge. Although not technically an IPN issue, if you do not encrypt communications, it is possible for a malicious party to capture the original transmission and change the price. Without this check, you could accept a lesser payment than expected without even realizing it.

PayPal generates an IPN message when you invoke certain API operations such as DoExpressCheckoutPayment or DoDirectPayment during checkout, or an Adaptive Payments operation such as Pay, Preapproval, or ExecutePayment. Figure 6-1 shows both the web flow and the IPN message authentication protocol.

Figure 6-1. Typical IPN flow

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, prepending the request parameters with cmd=_notify-validate. It is absolutely critical that the message 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.

PayPal recommends that you follow a specific checklist in handling IPNs:

1. Wait for an HTTP POST from PayPal.

2. Create a request that contains exactly the same IPN variables and values in the same order, preceded with the request parameters cmd=_notify-validate.

3. Post back the request to PayPal

4. Wait for a response from PayPal, which is either VERIFIED or INVALID.

5. Verify that the response status is 200.

6. If the response is VERIFIED, perform the following checks:

   • Confirm that the payment status is “Completed.” PayPal sends IPN messages for pending and denied payments as well; do not ship until the payment has cleared.

   • Use the transaction ID to verify that the transaction has not already been processed, which prevents duplicate transactions from being processed. Typically, you store transaction IDs in a database so that you know you are only processing unique transactions.

   • Validate that the receiver’s email address is registered to you. This check provides additional protection against fraud.

   • Verify that the price, item description, and so on, match the transaction on your website. This check provides additional protection against fraud.

7. If the verified response passes the checks, take action based on the value of the txn_type variable if it exists; otherwise, take action based on the value of the reason_code variable.

8. If the response is INVALID or the response code is not 200, save the message for further investigation.