Instant Payment Notification: Getting started

This guide presents these sections to quickly get you up and running with the PayPal Instant Payment Notification (IPN) service:


Instant Payment Notification (IPN) is a message service that notifies you of events related to PayPal transactions. The service is used to automate back-office and administrative functions on your web server, including fulfilling orders, tracking customers, and providing status and other information related to transactions.

Key concepts

The IPN message service sends you a notification when an event occurs that is related to one of your PayPal transactions. Typically, notifications are sent on events that represent a payment of some sort. However, notifications can also be triggered by authorizations, Fraud Management Filter actions, and various other actions (such as refunds, disputes, and chargebacks). Listed below are some events that can trigger a notification.

  • Instant payments (including Express Checkout payments, direct credit card payments, and calls made to the Adaptive Payments API)
  • eCheck payments (including payments with a status of pending, completed, and denied)
  • Pending payments (including payments being reviewed for potential fraud)
  • Authorizations (indicating a sale whose payment has not yet been collected)
  • Recurring payments and subscription payment actions
  • Chargebacks, disputes, reversals, and refunds associated with different transactions

You receive PayPal notifications through a listener application (also called a handler). The listener waits for messages from the IPN service. When a notification arrives, the listener verifies it and then passes it to a backend or administrative process that handles the message. The actions taken when a notification arrives can be varied and specific to your needs. For example, upon receipt of a notification, a listener can do any of the following:

  • Trigger an order fulfillment process (such as enabling a media download) when a payment is completed.
  • Update a list of customers or account records.
  • Create specialized "to do" lists based on the kind of notification received.

The diagram below shows the various events that can cause the IPN service to send your listener a notification, as well as the message flow between the IPN service and your listener.

IPN Process Flow
   Figure 1. IPN Flow

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 posts a message to your listener, notifying you of this event, which starts the request-response process.
  3. Your listener returns an empty HTTP 200 response.
  4. Your listener performs an HTTP POST to send the complete, unaltered notification back to PayPal, completing the initial request-response handshake, and allowing PayPal to verify that the IPN message is being sent to the correct location.

    Note: This message must contain the same fields, in the same order, as the original notification, 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).

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.

Receiving your first notification

To process a sample IPN message, build a listener and host it on your web server. Once the listener is up and running, test it by using the PayPal IPN Simulator tool. Once you have verified that your listener works with the IPN Simulator, you can then use the PayPal Sandbox to test and verify that your full payment flow works properly, as it will allow you to create simulated transactions and send simulated IPN message to the listener in an environment that emulates the live IPN environment.

The steps below include PHP snippets that show how to create a simple IPN listener. For full listener examples in PHP and other languages, please see the PayPal Code Samples page.

  1. Upon receipt of a notification from PayPal, send an empty HTTP 200 response.
       // Send an empty HTTP 200 OK response to acknowledge receipt of the notification 
       header('HTTP/1.1 200 OK'); 
  2. Extract variables from the notification for later processing.

    Note that how you process a particular notification depends on its type. For example, if a notification applies to a completed payment, you could extract these variables from the message:

      // Assign payment notification values to local variables
      $item_name        = $_POST['item_name'];
      $item_number      = $_POST['item_number'];
      $payment_status   = $_POST['payment_status'];
      $payment_amount   = $_POST['mc_gross'];
      $payment_currency = $_POST['mc_currency'];
      $txn_id           = $_POST['txn_id'];
      $receiver_email   = $_POST['receiver_email'];
      $payer_email      = $_POST['payer_email'];
  3. Use the notification to build the acknowledgement message required by the IPN authentication protocol.
      // Build the required acknowledgement message out of the notification just received
      $req = 'cmd=_notify-validate';               // Add 'cmd=_notify-validate' to beginning of the acknowledgement
      foreach ($_POST as $key => $value) {         // Loop through the notification NV pairs
        $value = urlencode(stripslashes($value));  // Encode these values
        $req  .= "&$key=$value";                   // Add the NV pairs to the acknowledgement
  4. Post the acknowledgement back to PayPal, so PayPal can determine whether the original notification was tampered with.
      // Set up the acknowledgement request headers
      $header  = "POST /cgi-bin/webscr HTTP/1.1\r\n";                    // HTTP POST request
      $header .= "Content-Type: application/x-www-form-urlencoded\r\n";
      $header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
      // Open a socket for the acknowledgement request
      $fp = fsockopen('tls://', 443, $errno, $errstr, 30);
      // Send the HTTP POST request back to PayPal for validation
      fputs($fp, $header . $req);
  5. Parse PayPal's response to your acknowledgement to determine whether the original notification was OK - if so, process it.
      while (!feof($fp)) {                     // While not EOF
        $res = fgets($fp, 1024);               // Get the acknowledgement response
        if (strcmp ($res, "VERIFIED") == 0) {  // Response contains VERIFIED - process notification
          // Send an email announcing the IPN message is VERIFIED
          $mail_From    = "";
          $mail_To      = "Your-eMail-Address";
          $mail_Subject = "VERIFIED IPN";
          $mail_Body    = $req;
          mail($mail_To, $mail_Subject, $mail_Body, $mail_From);
          // Authentication protocol is complete - OK to process notification contents
          // Possible processing steps for a payment include the following:
          // Check that the payment_status is Completed
          // Check that txn_id has not been previously processed
          // Check that receiver_email is your Primary PayPal email
          // Check that payment_amount/payment_currency are correct
          // Process payment
        else if (strcmp ($res, "INVALID") == 0) { Response contains INVALID - reject notification
          // Authentication protocol is complete - begin error handling
          // Send an email announcing the IPN message is INVALID
          $mail_From    = "";
          $mail_To      = "Your-eMail-Address";
          $mail_Subject = "INVALID IPN";
          $mail_Body    = $req;
          mail($mail_To, $mail_Subject, $mail_Body, $mail_From);
  6. Close the file and end the PHP script.

      fclose($fp);  // Close the file

Try it!

Next, you want to send a simulated IPN message to the listener you have hosted on your web server.

To do this, go to the PayPal Developer site and log in. Next, click Applications and then click the IPN simulator link (on the left). The IPN simulator appears.

IPN Simulator
   Figure 2. IPN Simulator

Finally, see the Instant Payment Notification (IPN) Simulator documentation for instructions explaining how to send various types of IPN messages to your listener.

Next steps

After testing and verifying your listener using the IPN Simulator, use the following suggestions to further test your IPN listener:

  1. Set up your Sandbox test environment.

    To make test calls, you need a Sandbox account, test users, and PayPal API credentials. If you have not yet set these up, do so now, as described in Testing NVP/SOAP API Calls.

  2. Review the IPN Integration Guide for a complete reference on how to set up an IPN listener and how to handle incoming IPN messages.
scroll to top