IPN Testing

This page contains information and instructions on IPN Testing and IPN troubleshooting. Testing your IPN listener ensures that it receives the IPN messages and handles them appropriately. This page contains the following main sections:

IPN testing methods

There are three distinct methods of testing your IPN listener when developing it and getting it ready to go live. Each of these methods are described below.

  1. Local development testing: This entails testing your IPN listener on your local development system to verify that it receives and correctly processes all of the fields that you require. This allows you to test all of your own backend processing without having to worry about the PayPal message verification process. This type of testing is typically the first testing done, and it's performed during the development of your listener on your local development system.
  2. IPN simulator testing: This type of testing allows you to use the IPN Simulator tool to send simulated IPN messages from the PayPal Sandbox to your listener. This testing method allows you to verify that your listener does handle the IPN message verification process without you having to go through the user login and payment process flow on your website to trigger an IPN message to be sent. This type of testing is typically performed once you have completed initial development of your listener and you want to verify that it correctly handles the IPN message verification and performs the correct backend processing based on the message data.
  3. IPN Sandbox testing: This entails testing your IPN listener using the PayPal Sandbox environment. The PayPal Sandbox testing allows you to test your entire flow including the user login, payment process, IPN message verification, and your backend processing, without having to make real payments using real credit cards in the live environment.

Once you have completed all your testing using the various testing methods and you are satisfied that the full flow works well, you are then ready to go live with your IPN solution on your production website. We recommend that once you go live with your IPN solution, that you do at least one real world using a real credit card, just to make sure everything is working properly before your customers hit the site.

Note: This page contains IPN Troubleshooting Tips and information. Information and troubleshooting for the IPN simulator testing are contained on the IPN Simulator documentation page.

Local development testing

When you first develop your IPN listener, you should test your backend automation processes and verify that they are working well before you attempt to test receiving and validating IPN messages from PayPal. The receiving and validation process is complex and should be tested on its own using the IPN simulator and then through standard sandbox testing, after you have developed, tested and verified your backend processing. This local IPN listener testing is where you should do initial testing of your backend processing.

Important: Because the listener page does not have a user interface, and just runs in the background, the local development method of testing is extremely important. You need to use this method to verify that your backend code is bug free before trying to test your page with either IPN Simulator or Sandbox test messages. With those methods of testing you cannot easily detect or troubleshoot bugs in your backend implementation. If you do have backend processing problems, it will make it very hard test the PayPal message handling verification because the verification may work, but since the backend implementation is broken, it will seem as if the message verification is not working.

Since the IPN listener accepts form input from a PayPal message, you can emulate that yourself locally to test your listener script by using HTML code similar to the code shown below. You just create a test page that submits a form with real field names and test values to emulate the data that might be sent by PayPal in an IPN message.

<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>

To view an example of this, and to see all the possible IPN values that PayPal might send in an IPN message, refer to sample IPN message.

Once you have created your initial listener, you can verify that the listener's "verified" code works as expected. To do that, 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 PayPal using form code as described above. Because a dummy IPN causes PayPal to return an INVALID message (since the message did not originate from PayPal), your "invalid" code will run, not your "verified". So temporarily moving your "verified" code to the "invalid" code section gives you a chance to check it locally, before moving to the next phase of the testing.

Note: Make certain to move your validate code back to it's original location, or put back your if statements so that when you go to the next method of testing, your listener will work according to the verification logic.

IPN Simulator testing

PayPal provides an IPN Simulator tool that you can use to send test IPN messages from the PayPal Sandbox to the URL at which your listener is running. The IPN Simulator tool allows you verify that your listener is receiving IPN messages and handling them correctly, without having to test you entire payment flow to receive an IPN message. IPN Simulator notifications include a test_ipn variable, which is not found in live IPN messages, so the IPN test messages can be distinguished from the real IPN messages.

See IPN Simulator for details on using the IPN Simulator.

IPN Simulator testing verification

The IPN Simulator itself will return a message that says "IPN sent successfully" as long as the value set in the IPN handler URL field is a valid URL, even if there is no listener at the URL, or even if there is a listener there and it's not working correctly. So, the only way to verify if the IPN messages are being received and handled properly is to verify that your backend process received the message and processed it correctly. There are a few ways that you can verify if the messages are being received correctly:

  1. You can simply open your database management software and view any database tables that may get added or modified by the listener backend code.
  2. You can create an IPN test verification page on your website that retrieves and displays database values that are added or modified by your listener backend code.
  3. You can use an existing page within your flow that already displays database values that would be modified by your listener backend code.
  4. You can isolate the verification code on your listener, and have it send you an email with all the data received, and the HTTP status code that indicates VERIFIED or INVALID, or you can create a database table specifically for the testing to store that same data for verification.

The last method is a good 'one step at a time' method that allows you to confirm that you are receiving and validating the messages correctly, before invoking or testing any of the backend code. When using this method, once you get an email (or test database table) that shows the correct values are received and the HTTP Status is set to VERIFIED, then you can remove the part that sends the email (or populates the database) and allow your backend code to run, because you have confirmed that your IPN messages are being received properly.

It is recommended that after you complete local testing of your IPN listener, and before testing your complete flow in the Sandbox environment, you should test it using the IPN Simulator.

PayPal sandbox testing for IPN

It is recommended to test your IPN listener in the Sandbox after you have completed some basic testing both locally and using the IPN Simulator.

There are two basic requirements when testing in the Sandbox.

  1. You need to change the code in your listener to post your response to the Sandbox URL at https://ipnpb.sandbox.paypal.com/cgi-bin/webscr, instead of the live URL https://ipnpb.paypal.com/cgi-bin/webscr.
  2. Your IPN listener must be implemented and running on your web server.

In order to test in the Sandbox, you must configure your Sandbox account with test merchant and buyer accounts. For more information, see the PayPal Sandbox guide.

Testing your IPN error notification code

Every listener must include code that handles the "error notification" IPN messages. To test the code for a given error notification IPN, log in to the Sandbox and initiate a payment with the amount field set to the negative testing trigger value for that IPN. The negative testing trigger amount 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 PayPal Sandbox Testing Guide. For more on negative testing, see Testing Error Conditions.

If you encounter any IPN issues while testing in the Sandbox, see the IPN troubleshooting tips for more information.

IPN troubleshooting tips

IPN failures typically fall into the following categories:

Not receiving any IPN messages from PayPal

If you do not receive any IPN messages from PayPal:

  • Check your IPN history on paypal.com.

    Note: IPN Simulator messages will not appear in your PayPal account IPN history.

    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: Do not use "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 than to your server.

  • Verify that your firewall is not blocking HTTPS 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, for example, for PayPal button code, do the following:

    Note: This type of IPN cannot be tested using the IPN Simulator.

    • 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 HTTPS POST method to redirect your customer to the specified return URL. This is required since PayPal sends IPNs as HTTPS POST requests.
    • Check that AutoReturn in your account profile is turned off.

Receiving some, but not all, IPN messages

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 PayPal account used in the transaction 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.

    Note: IPN Simulator messages will not appear in your PayPal account IPN history.

Receiving an INVALID message from PayPal

If you receive an INVALID message:

  • Check that you are posting your response to the correct URL:

    • Sandbox IPNs: https://ipnpb.sandbox.paypal.com/cgi-bin/webscr

    • Live IPNs: https://ipnpb.paypal.com/cgi-bin/webscr

    You will receive INVALID if you are testing in the sandbox and your listener posts back to the live site (or 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.

  • To ensure that symbols and special characters in the date or other fields are processed correctly, use rawurlencode and rawurldecode instead of urlencode and decode.

  • Ensure that you use the same character encoding for your response string as the encoding specified in the charset field of the original IPN message. When testing using the IPN Simulator, the character encoding will always be UTF-8.

Delayed IPN messages

If your IPN messages 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.

    Note: IPN Simulator messages will not appear in your PayPal account 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 OK responses 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:

    1. In your account profile, make sure that the IPN service is enabled.
    2. On the PayPal Status page, determine whether the PayPal servers are causing IPN delays. In Notification in the Product section, navigate to your API on the API tab.
    3. If you do not detect an IPN system issue or you need immediate help, open a support ticket on the PayPal Customer Support page. Include the following information:
      • The date and time stamps of the failed IPNs
      • The associated transaction IDs and, alternatively, the IPN activity type

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.