# IPN testing (/api/nvp-soap/ipn/IPNTesting)



> **Note:** **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](/).

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](#ipn-testing-methods)
* [Local development testing](#local-development-testing)
* [IPN simulator testing](#ipn-simulator-testing)
* [PayPal sandbox testing for IPN](#paypal-sandbox-testing-for-ipn)
* [IPN troubleshooting tips](#ipn-troubleshooting-tips)

## IPN testing methods [#ipn-testing-methods]

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

| Method                        | Description                                                                                                                                                                                                                                                                                                                                                          | Completed when                                                                                                                                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Local development testing** | To verify that the IPN listener receives and correctly processes all                 fields, test your IPN listener on your local development system. This                 method enables you to test all back-end processing without worrying                 about the PayPal message verification process.                                                        | During listener development on the local development system.                                                                                                                                 |
| **IPN simulator testing**     | Use the IPN Simulator tool to send simulated IPN messages from the                 PayPal sandbox to your listener. This testing method enables you to                 verify that your listener handles the IPN message verification process                 without user login and payment process flow on your website to trigger                 an IPN message. | You want to verify that the listener correctly handles the IPN message                 verification and completes the correct back-end processing based on the                 message data. |
| **IPN sandbox testing**       | Test your IPN listener by using the PayPal sandbox environment. Enables                 you to test your entire flow including the user login, payment process,                 IPN message verification, and your back-end processing.                                                                                                                              | You want to test without making real credit card payments in the live                 environment.                                                                                           |

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.

> **Note:** **Note:** This page contains
> [IPN Troubleshooting Tips](#ipn-troubleshooting-tips) and
> information. For IPN simulator testing information and troubleshooting, see
> [IPN Simulator](/api/nvp-soap/ipn/IPNSimulator/).

## Local development testing [#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.

> **Note:** **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 back-end 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 back-end implementation.
> If you do have back-end processing problems, it will make it very hard test
> the PayPal message handling verification because the verification may work,
> but since the back-end implementation is broken, it will seem as if the
> message verification is not working.

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.

<div className="pl-[1.625rem]" />

```html lineNumbers
<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"/> <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](/api/nvp-soap/ipn/IPNIntro/#a-sample-ipn-message-and-response).

To view an example of this, and to see all the possible IPN values that PayPal
might send in an IPN message, refer to
`VERIFIED`.
`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:** **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 [#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.

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
[IPN Simulator](/api/nvp-soap/ipn/IPNSimulator/) variable, which is not found in live IPN messages, so
the IPN test messages can be distinguished from the real IPN messages.

### IPN Simulator testing verification [#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 retrieve         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 indicate         `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.

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

## PayPal sandbox testing for IPN [#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.

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.

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](/sandbox-testing/overview).

### Test your IPN error notification code [#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.

| 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 how to use the sandbox, see
[PayPal Sandbox](/sandbox-testing/overview). For more on negative testing, see
[Testing Error Conditions](/sandbox-testing/error-handling).

For how to use the sandbox, see

## IPN troubleshooting tips [#ipn-troubleshooting-tips]

IPN failures typically fall into the following categories:

* [Not receiving any IPN messages from PayPal](#not-receiving-any-ipn-messages-from-paypal)
* [Receive some IPN messages](#receive-some-ipn-messages)
* [Receive an INVALID message from PayPal in response to your listener'             post back for validation](#receive-an-invalid-message)
* [Delayed IPN messages](#delayed-ipn-messages)

### Not receiving any IPN messages from PayPal [#not-receiving-any-ipn-messages-from-paypal]

If you do not receive any IPN messages from PayPal:

* Check your             [IPN history](https://www.paypal.com/us/cgi-bin/webscr?cmd=_display-ipns-history)             on paypal.com.

  > **Note:** **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 i             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.

  > **Note:** **Tip:** Do not use "localhost" URLs. Since IPN use                 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 thi             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:** **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 [#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](https://www.paypal.com/us/cgi-bin/webscr?cmd=_display-ipns-history)             to ensure that PayPal is posting each IPN to your listener.

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

### Receive an INVALID message [#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 field             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 [#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 fail             to send an `HTTP 200 OK` response for too many IPNs. Thi             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](https://www.paypal.com/us/cgi-bin/webscr?cmd=_display-ipns-history).

  > **Note:** **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-`POST`s.                                                                                                      |
  | `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-`POST`ed 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 a             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](https://www.paypal-status.com/) 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](https://www.paypal.com/us/smarthelp/home)                 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:** **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.