Instant Payment Notification

The NVP/SOAP APIs can use the Instant Payment Notification for event notification

APILegacyLast updated: December 11th 2023, @ 10:40:16 am

Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

Instant Payment Notification (IPN) is a message service that automatically notifies merchants of events related to PayPal transactions. Merchants can use it to automate back-office and administrative functions, including automatically fulfilling orders and providing customers with order status.

Why use Instant Payment Notification

Instant Payment Notification (IPN) notifies merchants almost instantly about transaction events, such as:

  • Payments received, including Express Checkout, and Adaptive Payments.
  • Credit card authorizations.
  • eCheck payments and related pending, completed, or denied status events.
  • Recurring payments and subscription actions.
  • Chargebacks, disputes, reversals, and refunds.

Merchants can use their backend processes to act based on the information they receive. For example, they can:

  • Update their inventory.
  • Email a purchase confirmation.
  • Trigger order fulfillment.
  • Enable download of digital media.
  • Update their customer list.
  • Email a shipping notification.
  • Issue a refund.
  • Update accounting-related information.

How it works

Merchants create an IPN listener page on their website and then specify the URL of the listener page in their PayPal account profile. PayPal then sends notifications of all transaction-related events to that URL. When customers pay for goods or services, PayPal sends a secure FORM POST containing payment information (IPN messages) to the URL. The IPN listener detects and processes IPN messages using the merchant backend processes. The IPN listener page contains a custom script or program that waits for the messages, validates them with PayPal, and then passes them to various backend applications for processing.

Use IPN in your checkout flow

Although PayPal usually processes IPN messages immediately, IPN is not synchronized with actions on your website. Internet connectivity is not always 100% reliable and IPN messages can be lost or delayed. The IPN service automatically resends messages until the listener acknowledges them. The service resends messages for up to 4 days.

Because IPN is not a real-time service, your checkout flow should not wait for the IPN message before it is allowed to complete. If the checkout flow is dependent on receiving an IPN message, processing can be delayed by system load or other reasons. You should configure your checkout flow to handle a possible delay.

Implement an IPN solution

To implement an IPN solution, you need to perform the following tasks:

  1. Plan your IPN Solution for both backend and listener: Decide which language you are going to use and review the PayPal IPN listener code samples. Plan what backend tasks need to be done for each type of IPN message (IPN Transaction Types) received.
  2. Implement and verify the PayPal request-response part of your listener: Create only the PayPal request-response part of your listener to verify that the required handshaking is working, without any backend code attached.
  3. Implement the listener backend functionality: Temporarily comment out the request-response handshaking part of the listener code since it is already verified as working, and then implement and verify that the backend part of your listener code is working.
  4. Test the listener: Uncomment the request-response code to test and verify that both the request-response handshaking and backend processes are working together as expected using the various different levels of recommended IPN testing methods, including the PayPal sandbox environment and the IPN simulator tool.
  5. Enable and verify the IPN messaging solution in your live environment: Enable IPN messaging in your PayPal account settings, and verify that both the PayPal request-response and backend are working correctly in the live environment. We recommend completing an actual test purchase on your website using a company credit card, and then keeping a close eye on the system for at least the first few transactions to make sure the solution is working smoothly. The IPN History page can help you track and review all IPN sent messages.

U.S. fees

There are no fees for Instant Payment Notification.

International availability and fees

You can use Instant Payment Notification in any country where PayPal is accepted. There are fees for currency conversion and to receive payments from another country. For more information, see PayPal Merchant Fees.

Developer and merchant support

This section contains information and resources that can help you in creating and working with your IPN solution.

IPN development resources