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 prefixed with the type of object:
     checkout_id=12345
    
     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):
     checkout_id=12345&reference_id=abc567
    
  • 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.


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 the object is in.


IPN Failures

If your callback_uri returns a non-200 response code when we make a HTTP request (including network retries), 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.

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

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!


Withdrawal IPNs

WePay sends IPNs to the account’s callback_uri for that account’s withdrawals. Identify withdrawals by the object identifier in the POST request:

withdrawal_id=1234

IPN List

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 state value that can be expected in most cases.
  • The “Additional Parameters” column outlines non-state parameters 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_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 IPN Trigger Object States Additional Parameters Bubbles Up
/account account_kyc_requires_documents action_required action_reasons None
account_kyc_verified active None
account_reviewed_by_risk
  • active
  • disabled
  • action_required
  • pending
  • statuses.account_review_status
  • disabled_reasons
bank_account_removed
  • action_required
  • action_reasons
  • disablement_time
bank_account_added active None
blacklist_status_changed disabled disabled_reasons
confirmed_registration
  • active
  • action_required
  • action_reasons
  • disablement_time
closed_for_loss disabled disabled_reasons
deleted deleted None
disablement_time_reached disabled disabled_reasons
undeleted active None
kyc_changed
  • active
  • action_required
  • action_reasons
  • disablement_time
  • /checkout authorized authorized in_review None
    review_started_manual authorized in_review
    review_passed_manual
    • failed
    • captured
    • released
    • authorized
    None
    captured captured None
    failed failed None
    cancelled cancelled None
    chargeback
    • charged_back
    • captured (indicates partial chargeback)
    chargeback.amount_charged_back
    chargeback_reversed captured chargeback.amount_charged_back
    expired None None
    refund
    • refunded
    • released
    • refund.amount_refunded
    • refund.refund_reason
    new new None
    refund_failed released None
    reserved authorized None
    succeeded released None
    /preapproval approved approved None None
    cancelled cancelled None
    completed completed None
    expired expired None
    revoked revoked None
    retrying retrying None
    stopped stopped None
    /reports complete complete None None
    deleted deleted None
    failed failed None
    processing processing None
    /user deleted deleted None None
    access_token_revoked *Any lookups in response to this IPN will result in an API error due to no access. Work directly with the user to get their account reconnected. None
    registered registered None
    updated_email registered email
    /withdrawal captured captured None Account
    enter_risk_review started in_review
    expired expired None
    failed failed None
    new new None
    pass_risk_review
    • captured
    • failed
    • started
    None
    authorized started in_review