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.
object_idwill be in the body of the request (and not added as a url-parameter).
object_idwill be prefixed with the type of object:
- For checkouts and preapprovals, the
reference_idwill also be in the body of the request (if a
- 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 (ex /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.
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 the object is in.
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.
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
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.
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).
An IPN is sent if a credit card becomes invalid for any reason. The
credit_card object state is ‘deleted’.
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!
WePay sends IPNs to the account’s
callback_uri for that account’s withdrawals. Identify withdrawals by the object identifier in the POST request:
Below is a list of IPNs that are associated with each API call.
- The “Call” column identifies the endpoint to call in order to get information related to the IPN.
- The “IPN Trigger” column describes the typicall conditions which trigger that IPN.
- The “Object States” column outlines the object’s
statevalue that can be expected in most cases.
- The “Additional Parameters” column outlines non-
stateparameters that should be examined in order to get the relevant updated information about the object.
- The “Bubbles Up” column illustrates the relationship between the API calls. If
callback_uriis not set at a call, it will bubble up to the above layer until it finds a layer with a
|Call||IPN Trigger||Object States||Additional Parameters||Bubbles Up|