IPN simulator

APILegacyLast updated: December 11th 2023, @ 12:40:16 pm

Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

You can use the IPN simulator tool to send test IPN messages from the PayPal sandbox to the URL at which your listener is running. The IPN simulator allows you to verify that your listener is receiving IPN messages and handling them correctly. 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.

IPN listener requirements

There are two basic requirements when using the IPN Simulator to send IPN messages from the PayPal sandbox:

You have 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 at https://ipnpb.paypal.com/cgi-bin/webscr. This URL cannot be localhost. The sandbox notification URL does not have to be set up in your PayPal account profile but you must set up your live URL in your PayPal account profile.
Your IPN listener must be implemented and running on your web server.

Note: To use the IPN simulator, you must be logged into the PayPal Developer site, and your listener must be running at your notification URL on your web server.

Important: Because the listener page does not have a user interface, and runs in the background on your web server, it is extremely important that you have already performed local development testing on your listener to verify that the backend processes are working properly. If there are errors in your backend code, it will be extremely hard to verify that the IPN message validation process is working.

Before testing with the IPN Simulator, we recommend you review the recommended verification procedures in IPN Testing.

Using the IPN simulator

To use the IPN simulator, follow these steps:

Go to the PayPal Developer) site and log in.
In the IPN handler URL text box, enter the URL of the listener to which you want to send a test IPN notification message.
From the Transaction type dropdown menu, select the type of transaction for which you want to send an IPN message.
This simulator opens an input form for the specified IPN message, 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.
In the fields of the input form, enter the values that you want to send in your test IPN message.
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.

The default messages sent by the IPN simulator are valid. If your IPN listener receives the test message, you know the listener is properly installed on your web server. 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, see IPN Simulator troubleshooting.

IPN simulator testing verification

The IPN Simulator itself will display an 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 backend process received the message and processed it correctly. There are a few ways to determine if the messages are being received correctly. You can:

Open your database management software and view any database tables that may get added or modified by the listener backend code.
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.
Use an existing page within your flow that already displays database values that would be modified by your listener backend code.
Isolate the verification code on your listener, and have it send you an email with all the data received, and the HTTP status that indicates VERIFIED or INVALID, or you can create a database table specifically for testing to store that same data for verification.

The last method in the preceding list 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, after 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.

There are a few cases where the simulator will return an HTTP status code, other than the 200 success code, such as:

If you enter a URL that cannot be found, the IPN simulator displays: We could not send an IPN due to an HTTP error: 404: Not Found.
If you enter an invalid URL, such as a URL that is not preceded by https://, the simulator displays: Please enter a valid URL.

For all other cases, you can look up the message on the HTTP Status Codes page.

Note: Entering a URL that includes www.paypal.com will not work. This causes the simulator to return an HTTP status code in the 300 range.

IPN simulator troubleshooting

These troubleshooting tips can be helpful in situations where the IPN simulator is displaying an IPN sent successfully message, but you are not able to validate that the message content was received and/or you are receiving an HTTP status of INVALID, rather than the expected VERIFIED status.

Confirm that the code in your listener is set 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.
Confirm that your listener page is actively running and ready to receive IPN messages. Repeat the local development testing on the listener, if necessary, to confirm that the page is running.
Isolate the IPN message verification code on your page, and comment out all the backend processing, similar to the IPN code samples at: IPN code samples. This will allow you to more easily test and verify the message verification code, without depending upon your backend processing to work properly. When you do this, you need to use some type of method that allows you to verify that the listener is working. The recommended method is to create a database table specifically for the testing and then store the HTTP status returned by PayPal and possibly some or all of the expected IPN message values. This enables you to view the tables after sending IPN simulator messages to verify whether message processing works or not. If it's still not working as expected, you should do local testing on your listener page to verify that the page is sending values to your test database table.
Everything seems to be working, but you are still receiving the HTTP status of INVALID and you have confirmed that your listener code is set to post your response to the sandbox URL at https://ipnpb.sandbox.paypal.com/cgi-bin/webscr. In this case, the problem is most likely that your listener is not sending a properly formatted reply string to PayPal. That string needs to contain the unaltered message to send back to PayPal; the message must contain the same fields (in the same order) as the original message and be character encoded in the same way as the original message, and must be preceded with a cmd=_notify-validate variable.

For further troubleshooting, see IPN Troubleshooting Tips