Instant Payment Notification: Getting Started

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

Overview

Instant Payment Notification (IPN) is a message service that notifies you of events related to PayPal transactions. You can use this service to automate back-office and administrative functions, 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 passes it to a back-end 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 HTTP POSTs your listener a message that notifies you of this event.
  3. Your listener returns an empty HTTP 200 response.
  4. Your listener HTTP POSTs the complete, unaltered notification back to the PayPal.
    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 Sandbox to send a simulated IPN message to the listener.

The steps below include PHP snippets that show how to code a simple IPN listener.

  1. Upon receipt of a notification from PayPal, send an empty HTTP 200 response.
    <?php
    
       // 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('ssl://www.sandbox.paypal.com', 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    = "IPN@example.com";
          $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    = "IPN@example.com";
          $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 Using the Instant Payment Notification (IPN) Simulator section of Testing Classic API Calls for instructions explaining how to send various types of IPN messages to your listener.

Next Steps

Use the following suggestions to enhance your understanding of Instant Payment Notifications:

  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 Classic API Calls.

  2. Review the Instant Payment Notification Guide for a complete reference on how to set up an IPN listener and how to handle incoming IPN messages.