Paypal Button and Instant Payment Notification (IPN) – Overview, Protocol and Architecture

This post is intended for those who hate to read long documentation. I’ve tried to capture “minimum” reading material from Paypal website, that is required to understand Paypal IPN Protocal and Architecture and which is a pre-requisite for our example of integration of Paypal Button and Instant Payment Notification (IPN) with Java. If you want to learn more, you should definitely read more details from Paypal website.

Instant Payment Notification (IPN) is PayPal's message service that sends a notification when a transaction is affected. Once IPN is integrated, sellers can automate their back office so they don’t have to wait for payments to come in to trigger order fulfillment. [Source: Paypal]

For Paypal Button and IPN integration, you have to create an “IPN Listener” that should be exposed publicly on internet so that Paypal server(s) can send notifications to your IPN listener and from there you can start your own business flow to process those notifications.

Technically in Java, an “IPN Listener” can be exposed on some URL that could be mapped to a Java Servlet, a JSP Page, a Struts Controller and Action, a Spring Controller, etc.

The following diagram shows how events can occur and how PayPal responds with IPN messages that it sends to your listener:

 

The diagram shows requests and responses, which are the result of processing paypal button clicks. 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 authentication 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

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; 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 resends 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.

[Source: Paypal]