Introducing OnlineNaira IPN

Instant Payment Notification (IPN) is a message service that notifies you of events related to OnlineNaira 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:

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:

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. This 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:

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:

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

IPN Message Generation and Flow

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

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.