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
• Local development testing
• IPN simulator testing
• PayPal sandbox testing for IPN
• IPN troubleshooting tips

IPN testing methods

Use these methods to test your IPN listener before you go live:

After you complete testing and you are satisfied that the full flow works well, you can go live with your IPN solution on your production website. We recommend that once you go live with your IPN solution, you complete at least one real-world test with a real credit card, just to make sure everything is working properly before your customers access the site.

Local development testing

When you first develop your IPN listener, you should test your back-end 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 back-end processing. This local IPN listener testing is where you should do initial testing of your back-end processing.

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

1<form target="_new" method="post"
2        action="https://www.YourDomain.com/Path/YourIPNHandler.php"> <input
3        type="hidden" name="SomePayPalVar" value="SomeValue1"/> <input
4        type="hidden" name="SomeOtherPPVar" value="SomeValue2"/> <input
5        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.

After you create 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.

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.

For IPN Simulator details, see IPN Simulator.

IPN Simulator testing verification

The IPN Simulator returns a IPN sent successfully message 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 back-end 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 back-end 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 back-end code.
3. You can use an existing page within your flow that already displays database values that would be modified by your listener back-end 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 back-end 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 back-end 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.

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.

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

For how to use the sandbox, see PayPal Sandbox. For more on negative testing, see Testing Error Conditions.

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

IPN troubleshooting tips

IPN failures typically fall into the following categories:

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

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, the listener script might contain an error. Often, your language error log tells 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.

Receive some 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.

Receive an INVALID message

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 that 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 includes some or all these entries:

  Sent	PayPal sent the message to your IPN listener.
  Failed	PayPal never received an HTTP 200 OK response to the original POST or to any of the subsequent re-POSTs.
  Queued	PayPal is ready to send the message.
  Retrying	PayPal did not receive an HTTP 200 OK response to the original POST, the message has been re-POSTed between one and fifteen times, and PayPal is continuing to re-POST the message.
  Disabled	The message is not resent because either IPN or the account was 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 posts IPNs from the faster-cycling server.

• If your IPN history does not contain any Failed entries:

  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