In this section:
In this section:

Instant Payment Notifications (IPN)

Instant Payment Notifications (IPNs) allow you to receive notifications whenever the state on an object changes (or something important happens to that object).

To set up IPNs for an object, set a callback_uri on that object. Whenever something important happens to the object that we think you should be notified of (typically a state change), we will make an HTTP POST request to your callback_uri with the object_id in the body of the request.

IPN HTTP Request Details

The HTTP request that we make to your callback_uri will have the following characteristics:

  • It will be a POST request
  • The object_id will be in the body of the request (and not added as a url-parameter)
  • The object_id will be named for the type of object (for example checkout_id=12345 or account_id=51232)
  • For checkouts and preapprovals, the reference_id will also be in the body of the request (if a reference_id was set).
  • We will preserve any url-parameters you add to the callback_uri (so you could receive a POST request to http://example.com/ipn?user=12345)

What to do when you receive an IPN

When you receive an IPN, you should use the relevant API call to look up the object’s updated information. For example, if you received an IPN for a checkout, you would receive the checkout_id in the HTTP request POST data. You would then make the /checkout call to look up the new information for the checkout.

IPNs themselves don’t include state information. The canonical source for information about the object is the relevant API call (e.g., /checkout ). We do this so that you don’t have to verify the IPN itself. Because HTTPS/SSL verifies the identity of the server you are making API calls to, you will always know that the updated information you are receiving is correct. If we sent object information in the IPN itself, you would have to verify the authenticity of the information (via signed request, etc). The IPN is only a notification that the state on an object has changed and you should look up the new information.

IPN Batching

We will batch IPNs for the same object that are very close together. So if a checkout goes from state new to authorized to captured immediately, you will only receive one IPN and when you look up the state of the checkout it will be captured. The advantage of doing this is that it prevents us from overwhelming your server(s) with HTTP requests and it prevents your app from having to build complicated logic around sequential state changes. Your app should only care about the latest state of the object.

IPN Failures

If your callback_uri returns a non-200 response code when we make a HTTP request, we will consider the IPN to have failed. If the IPN fails, we will retry at least 6 times:

  • The 1st retry will happen 15 minutes after the initial attempt,
  • the 2nd retry will happen 30 minutes after the 1st retry,
  • the 3rd retry will happen 1 hour after the 2nd retry,
  • the 4th retry will happen 6 hours after the 3rd retry,
  • the 5th retry will happen 12 hours after the 4th retry,
  • and the 6th retry will happen 24 hours after the 5th retry.

Subscription IPNs

If you are using the /preapproval/create call and set auto_recur to true, then we will be creating checkout objects automatically for you every period (month, year, etc). In this case, if you set a callback_uri on the /preapproval/create call, we will send IPNs for the checkouts to that callback_uri.

Account Updater IPNs

WePay sends two different IPNs if you are using Account Updater to automatically update credit cards that have been stored with WePay.

  1. An IPN is sent if a credit card is updated automatically; the credit_card object state remains authorized, but the card now has new information (last four digits and expiration date).
  2. An IPN is sent if a credit card becomes invalid for any reason. The credit_card object state is deleted.

Warning

Testing IPNs on your local machine

Please note that in order for IPNs to work, your callback_uri MUST be publicly available.

If you are doing development on your local machine it is likely that your callback_uri will not be reachable. Our server cannot connect to localhost!

IPN List

Below is a list of IPNs that are associated with each API call. The Bubbles Up column illustrates the relationship between the API calls. If callback_uri is not set at a call, it will bubble up to the above layer until it finds a layer with a callback_uri set.

Call IPNs Bubbles Up
/account blacklist_status_changed None
deleted
undeleted
/checkout new None
started
succeeded
failed
throttled
/preapproval new None
started
succeeded
failed
throttled
/withdrawal new Account
started
succeeded
failed
throttled