IPN Testing

Once you have implemented your listener and installed it on your web server, you can use the Sandbox's IPN simulator to send test IPN messages to the URL at which your listener is running. This tool lets you verify that your listener is receiving IPN messages and handling them correctly.

Testing Your Listener

The IPN simulator lets you send test IPN messages to your listener, so you can verify that it receives and handles such messages correctly. The only difference between a notification sent by the Simulator and a live IPN message is that a test IPN includes the test_ipn variable.

Note: To use the IPN simulator, you must be logged into the Sandbox. Further, a listener must reside at the URL you specify. However, this URL does not have to be entered in your account profile - the simulator will send an IPN to any listener you specify. Finally, the IPN simulator does not support all PayPal API operations.

To use the IPN simulator, follow these steps:

  1. Go to the PayPal Developer site and log in.
  2. Click Applications.
    A list of tools appears on the left side of the page.
  3. Click IPN simulator.
    The IPN simulator appears.

    IPN Simulator

  4. In the IPN handler URL text box, enter the URL of the listener to which you want to send a test IPN notification message.
  5. From the Transaction type dropdown menu, select the type of transaction for which you want to send an IPN message.
    An input form specific to the specified IPN message appears, with most fields populated with test data.
    Note: For each type of IPN message, the simulator displays the most commonly used fields. To see all possible fields, click Show All Fields (at the bottom of the form).
  6. In the fields of the input form, enter the values you want to send in your test IPN message.
  7. Click Send IPN (at the bottom of the form).
    The simulator sends a single copy of the specified IPN message to the specified listener and displays the results at the top of the page.

If your IPN listener receives the test message, you know the listener is properly installed on your web server. The default messages the IPN simulator sends are valid. Therefore, if your listener responds correctly to such a message, your listener should next receive a VERIFIED response message. If you do not receive any message or if you receive an INVALID message from PayPal after responding to the original test IPN message, you must troubleshoot your listener.

Testing Your IPN Error Notification Code

Every listener must include code that handles the "error notification" IPN messages listed in the table below.

To test the code for a given error notification IPN, log in to the Sandbox and initiate a payment whose amount variable is set to the negative testing trigger value for that IPN. The negative testing trigger for each error notification IPN is listed below.

Error Condition Negative Testing Trigger
Transaction Pended (API + IPN) Set amount to 11.22
Transaction Declined (API Error Code 13122) Set amount to 131.22
Transaction Blocked after Pending (IPN) Set amount to 21.22
Transaction Rejected after Pending (IPN) Set amount to 31.22
Transaction Reversed due to exceeding SLA after Pending (IPN) Set amount to 41.22
Transaction Pended then Released (API + IPN) Set amount to 51.22

For instructions explaining how to use the Sandbox, see Testing Classic API Calls. For more on negative testing, see Testing Error Conditions.

IPN Troubleshooting Tips

IPN failures fall into these categories:

  • Not receiving any IPN messages from PayPal
  • Receiving some, but not all, IPN messages
  • Receiving an INVALID message from PayPal in response to your listener's post back for validation
  • Delayed IPN messages

If you do not receive any IPN messages from PayPal:

  • Check your IPN history on paypal.com.
    Your IPN history tells you whether PayPal sent a given IPN message and whether your listener responded to it. This page may also provide information about the status of the server on which your listener is running. If necessary, you can request that PayPal re-send a given IPN message via the IPN history page.
  • Check that the path to your IPN listener is correct and that you are using this path correctly in your IPN notification URL.
    Tip: Avoid using "localhost" URLs. Since IPN uses back-end, server-to-server communication, setting a path to localhost causes the IPN service to post to itself rather to your server/script.
  • Verify that your firewall is not blocking HTTP POST request messages from PayPal.
  • Check your web server's access and error logs.
    The access log tells you whether your server is receiving IPN messages at all, while the error log lists any errors that have occurred on your server.
  • Check your programming language's error log.
    Many scripting languages write to a log if an error occurs while executing a script. If your web server's access log shows that PayPal is sending IPNs, but your listener is not responding as expected, it may contain an error. Often, your language error log will tell you what this error is and where it occurs in your listener script.
  • For IPNs configured to be sent to your return URL:
    • Verify that the return variable in your button code is set to your listener's URL. This variable defines the URL to which your customer is redirected upon completing payment at paypal.com.
    • Ensure that the rm variable in your button code is set to 2, so PayPal uses the HTTP POST method to redirect your customer to the specified return URL. This is required since PayPal sends IPNs as HTTP POST requests.
    • Check that AutoReturn in your account profile is turned off.

If you receive some messages, but not others:

  • Verify that your IPN listener is responding to all messages, even those you do not intend to process.
  • Check that the account is valid and confirmed.
    If you send money to an unconfirmed account, PayPal will not send an IPN message.
  • Check the URLs listed in your IPN history to ensure that PayPal is posting each IPN to your listener.

If you receive an INVALID message:

  • Check that your listener is posting the response to the correct URL - https://www.sandbox.paypal.com/cgi-bin/webscr (for Sandbox IPNs) or https://www.paypal.com/cgi-bin/webscr (for live IPNs). You will receive INVALID if you are testing in the Sandbox and your listener posts back to the live site (and vice versa).
  • Verify that your response to an IPN:
    • contains exactly the same variables and values as the original IPN.
    • places these variables and values in the same order as does the original IPN.
    • precedes these variables with a cmd=_notify-validate variable.
  • Ensure that you use the same character encoding (for example, UTF-8) for your response string as the original IPN used.
    Tip: The charset variable in the original IPN tells you what character encoding to use for your response message. In addition, check for any non-standard characters in the original IPN, such as an accented character.

If your IPNs are delayed:

  • Make sure your listener sends an HTTP 200 OK response to each IPN it receives from PayPal.
    IPN delays occur if your listener fails to send an HTTP 200 OK response for too many IPNs. This happens because PayPal re-sends each IPN for which it does not receive an HTTP 200 OK response. Once a certain number of re-sends are in progress, your IPNs are moved to a slower-cycling server, which produces the delays.

    To find out if not sending HTTP 200 OK responses is the cause of your IPN delays, check your IPN history. Your IPN history will include some or all of these entries:

    • Sent - indicates that PayPal sent the message to your IPN listener
    • Failed - indicates that PayPal never received an HTTP 200 OK response to the original POST or to any of the subsequent re-POSTs
    • Queued - indicates that PayPal is ready to send the message
    • Retrying - indicates that PayPal did not receive an HTTP 200 OK response to the original POST, the message has been re-POSTed between 1 and 15 times, and PayPal is continuing to re-POST the message
    • Disabled - indicates that the message will not be resent because either IPN or the account has been disabled

    If you see many Failed or Retrying entries, not sending HTTP 200 OK responses is probably causing your IPN delays. To fix this, go through your server logs to determine why HTTP 200 OKs are not being sent and fix your listener. Once your listener is sending HTTP 200 OK responses as required, PayPal will post IPNs from the faster-cycling server.

  • If there are no Failed entries in your IPN history:
    • First, ensure that the IPN service is still enabled in your account profile.
    • Next, determine whether the PayPal servers themselves are causing IPN delays.
      • To find out, go to the PayPal Notifications page, select Order Management (IPN/PDT) from the Select Product dropdown menu, and click Search. In the response that appears, look for any PayPal system issue that might be causing IPN delays. If you find such an issue, if possible, please wait a few hours for PayPal to fix the problem - then try again.
    • If there is no IPN system issue, or you need immediate help, go to the PayPal Customer Support page. In your support ticket, include such information as:
      • the timestamps of the IPNs that are failing
      • the associated transaction Ids and/or the type of IPN activity
      • the date/times at which you expected the IPNs to arrive

Other troubleshooting tips:

  • Test your IPN listener locally.
    Use HTML code like that below to test your listener script.
    <form target="_new" method="post" action="https://www.YourDomain.com/Path/YourIPNHandler.php">
      <input type="hidden" name="SomePayPalVar" value="SomeValue1"/>
      <input type="hidden" name="SomeOtherPPVar" value="SomeValue2"/>
    <!-- code for other variables to be tested ... --> <input type="submit"/> </form>
  • Verify that your your listener's "verified" code works as expected.
    Copy the code that runs if PayPal's response is VERIFIED to the part of your listener that runs if a response is INVALID. Next, post a dummy IPN to your listener. Because a dummy IPN causes PayPal to return INVALID (since the message did not originate from PayPal), your "verified" code will run, giving you a chance to check it.

Note: If you receive multiple IPN messages for the same transaction or if messages appear to be out of order, this does not necessarily indicate that your listener is malfunctioning. For example, if your listener does not respond to an IPN in time, PayPal automatically re-sends it. That said, you should still investigate such occurrences because they could be caused by logic errors or performance problems.