Instant Payment Notification: Getting started

Get up and running with the PayPal Instant Payment Notification (IPN) service:

Overview

Instant Payment Notification (IPN) is a message service that notifies you of events related to your PayPal transactions. This service provides status notifications and other information related to your transactions, and these notifications can be used to automate back-office and administrative functions, including fulfilling orders and tracking customer 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 — includes Express Checkout payments, direct credit card payments, and Adaptive Payments
  • eCheck payments — includes payments with a status of pending, completed, and denied
  • Pending payments — includes payments being reviewed for potential fraud
  • Authorizations — a payment that is authorized but 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 an IPN listener application that you develop (also called a handler). The listener resides on your servers and waits for messages from PayPal's IPN service. When a notification arrives, the listener verifies it and then passes it to your 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 could perform 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 PayPal's IPN service to send your listener a notification, as well as the message flow between the IPN service and your listener.

IPN Process 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 as configured, such as printing a packing list, enabling 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.

  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. Use the notification to build the acknowledgement message required by the IPN authentication protocol.

    // read the IPN notification from PayPal and add the 'cmd' parameter to the beginning of the acknowledgement you will send back
    $req = 'cmd=_notify-validate';
    
    // Loop through the notification name-value pairs
    foreach ($_POST as $key => $value) {
    	// Encode the values
        $value = urlencode(stripslashes($value));
        // Add the name-value pairs to the acknowledgement
        $req .= "&$key=$value";
    }
    
  3. Post the acknowledgement back to PayPal, so PayPal can determine whether the original notification was tampered with.

    // post back to PayPal system to validate
    $header = "POST /cgi-bin/webscr HTTP/1.1\r\n";
    
    // Set up other acknowledgement request headers
    $header .= "Content-Type: application/x-www-form-urlencoded\r\n";
    $header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
    
    // If testing on Sandbox use:
    $header .= "Host: www.sandbox.paypal.com:443\r\n";
    // For live servers use $header .= "Host: www.paypal.com:443\r\n";
    
    // Open a socket for the acknowledgement request
    // If testing on Sandbox use:
    $fp = fsockopen ('ssl://www.sandbox.paypal.com', 443, $errno, $errstr, 30);
    // For live servers use $fp = fsockopen ('ssl://www.paypal.com', 443, $errno, $errstr, 30);
    
    // Send the HTTP POST request back to PayPal for validation
    fputs($fp, $header . $req);
    
  4. 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);
    		}
    
  5. Close the file and end the PHP script.

    	fclose ($fp);
    }
    ?>
    

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 the Dashboard link. Then select Sandbox > IPN Simulator link (on the left).

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 PayPal Sandbox Testing Guide.

  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.

back to top