PayPal IPN WordPress Hooks Guide

by | Last Updated Oct 21, 2018 | Published on Jan 17, 2015 | PayPal IPN for WordPress | 36 comments

Introduction

PayPal IPN for WordPress provides a number of hooks so that you can automate tasks within your own plugins/themes based on the type of IPN that was sent or the payment status of a transaction. This allows you to easily extend the plugin to suit your needs.

Note

Don’t forget to check out our developer guide if you need some guidance on building your own hook functions.

PayPal IPN WordPress Hooks Library

Most of the hooks provided by the plugin will be based on the txn_type or payment_status value sent in the IPN and will always be all lowercase. The following list includes all of the hooks that are currently available.

Catch-All Hook

paypal_ipn_for_wordpress_ipn_response_handler

This is a “catch-all” hook that is triggered with all IPN transactions regardless of the type or payment status.

Verification Hooks

paypal_ipn_for_wordpress_ipn_response_verified

The IPN being processed has been successfully verified by PayPal.

NOTE:  You can also check the status of the IPN from within any other hook function using $posted[‘IPN_status’].

paypal_ipn_for_wordpress_ipn_response_invalid

The IPN being processed failed verification with PayPal and is considered invalid.

NOTE:  You can also check the status of the IPN from within any other hook function using $posted[‘IPN_status’].

Transaction Type Hooks

paypal_ipn_for_wordpress_txn_type_adjustment

A dispute has been resolved and closed.

paypal_ipn_for_wordpress_txn_type_cart

Payment received for multiple items; source is Express Checkout or the PayPal Shopping Cart.

paypal_ipn_for_wordpress_txn_type_express_checkout

Payment received for a single item; source is Express Checkout.

paypal_ipn_for_wordpress_txn_type_masspay

Payment sent using MassPay.

paypal_ipn_for_wordpress_txn_type_merch_pmt

Monthly subscription paid for Website Payments Pro.

paypal_ipn_for_wordpress_txn_type_mp_cancel

Billing agreement cancelled.

paypal_ipn_for_wordpress_txn_type_mp_signup

Created a new billing agreement.

paypal_ipn_for_wordpress_txn_type_new_case

A new dispute was filed.

paypal_ipn_for_wordpress_txn_type_payout

A payout related to a global shipping transaction was completed.

paypal_ipn_for_wordpress_txn_type_pro_hosted

Payment received; source is Website Payments Pro Hosted Solution.

paypal_ipn_for_wordpress_txn_type_recurring_payment

Recurring payment received.

paypal_ipn_for_wordpress_txn_type_recurring_payment_expired

Recurring payment expired.

paypal_ipn_for_wordpress_txn_type_recurring_payment_failed

Recurring payment failed.

paypal_ipn_for_wordpress_txn_type_recurring_payment_skipped

Recurring payment skipped.

paypal_ipn_for_wordpress_txn_type_recurring_payment_profile_cancel

Recurring payment profile has been canceled.

paypal_ipn_for_wordpress_txn_type_recurring_payment_profile_created

Recurring payment profile has been created.

paypal_ipn_for_wordpress_txn_type_recurring_payment_suspended

Recurring payment has been suspended. This transaction type is sent if PayPal tried to collect a recurring payment, but the related recurring payments profile has been suspended.

paypal_ipn_for_wordpress_txn_type_recurring_payment_suspended_due_to_max_failed_payment

Recurring payment failed and the related recurring payment profile has been suspendedThis transaction type is sent if:

  • PayPal’s attempt to collect a recurring payment failed
  • The “max failed payments” setting in the customer’s recurring payment profile is 1 or greater
  • The number of attempts to collect payment has exceeded the value specified for “max failed payments” In this case, PayPal suspends the customer’s recurring payment profile.
paypal_ipn_for_wordpress_txn_type_send_money

Payment received; source is the Send Money tab on the PayPal website.

paypal_ipn_for_wordpress_txn_type_subscr_cancel

Subscription canceled.

paypal_ipn_for_wordpress_txn_type_subscr_eot

Subscription expired.

paypal_ipn_for_wordpress_txn_type_subscr_failed

Subscription payment failed.

paypal_ipn_for_wordpress_txn_type_subscr_modify

Subscription profile modified.

paypal_ipn_for_wordpress_txn_type_subscr_payment

Subscription payment received.

paypal_ipn_for_wordpress_txn_type_subscr_signup

Subscription started.

paypal_ipn_for_wordpress_txn_type_virtual_terminal

Payment received; source is the Virtual Terminal

paypal_ipn_for_wordpress_txn_type_web_accept

Payment received; source is any of the following:

  • A DoDirectPayment (Pro) credit card transaction
  • A Buy Now, Donation or Smart Logo for eBay Auctions button

Payment Status Hooks

paypal_ipn_for_wordpress_payment_status_canceled_reversal

A reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you.

paypal_ipn_for_wordpress_payment_status_completed

The payment has been completed, and the funds have been added successfully to your account balance.

paypal_ipn_for_wordpress_payment_status_created

A German ELV payment is made using Express Checkout.

paypal_ipn_for_wordpress_payment_status_declined

The payment was declined. This happens only if the payment was previously pending because of one of the reasons listed for the pending_reason variable or the Fraud_Management_Filters_x variable.

paypal_ipn_for_wordpress_payment_status_expired

This authorization has expired and cannot be captured.

paypal_ipn_for_wordpress_payment_status_failed

The payment has failed. This happens only if the payment was made from your customer’s bank account.

paypal_ipn_for_wordpress_payment_status_pending

The payment is pending. See pending_reason for more information.

paypal_ipn_for_wordpress_payment_status_refunded

You refunded the payment.

paypal_ipn_for_wordpress_payment_status_reversed

A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the reason_code parameter.

paypal_ipn_for_wordpress_payment_status_processed

A payment has been accepted.

paypal_ipn_for_wordpress_payment_status_voided

This authorization has been voided.

Adaptive Payments Transaction Type Hooks

paypal_ipn_for_wordpress_adaptive_adaptive_payment_preapproval

An Adaptive Payments Preapproval profile has been created.

paypal_ipn_for_wordpress_adaptive_adaptive_payment_pay

An Adaptive Payments payment has been processed.

Adaptive Payments Status Hooks

paypal_ipn_for_wordpress_adaptive_status_canceled

An Adaptive Payments payment has been canceled.

paypal_ipn_for_wordpress_adaptive_status_created

An Adaptive Payments payment has been created.

paypal_ipn_for_wordpress_adaptive_status_completed

An Adaptive Payments payment has completed successfully.

paypal_ipn_for_wordpress_adaptive_status_incomplete

An Adaptive Payments payment is incomplete.

paypal_ipn_for_wordpress_adaptive_status_error

An Adaptive Payments payment failed with an error.

paypal_ipn_for_wordpress_adaptive_status_reversalerror

An Adaptive Payments payment reversal failed with an error.

paypal_ipn_for_wordpress_adaptive_status_processing

An Adaptive Payments payment is processing.

paypal_ipn_for_wordpress_adaptive_status_pending

An Adaptive Payments payment is pending.

Need Additional Help?

Schedule a live meeting with Drew Angell, PayPal Certified Developer, and get all of your questions or concerns answered.

Get Direct Help from a PayPal Partner

Featured PayPal Products and Services

36 Comments

← Older Comments
  1. Ed Hobbs
    Ed Hobbs on July 2, 2017 at 3:30 pm

    I am looking for a simple way to get the information PayPal sends back upon a successful membership purchase transaction or the e-mail itself sent to our accountant since PayPal will only allow one e-mail address to get that e-mail. Have your PayPal IPN plugin installed and I am not a super technical person and can’t “see” the next step.

    The website is a test version as a subdomain of another personal site I have. Am migrating our existing http://www.mwtca.org Joomla site to WordPress for ease of support. We are an all volunteer, not for profit association of antique tool collectors.

    Thanks so much in advance for your help!!! Ed

    Reply
    • Andrew Angell
      Andrew Angell on July 2, 2017 at 8:27 pm

      Hi Ed,

      The hook functions can go in your theme’s functions.php file or within your own plugin. I would recommend doing it from within your own plugin, which is very simple. Download this plugin template, and you’ll see it’s setup with a single hook function. This sample function sends an email to a given address for all IPNs that hit the site, which is what the “paypal_ipn_for_wordpress_ipn_response_handler” hook is for.

      All you need to do is customize the function so that it builds a more complete email that you’d like to send, and then you may want to adjust the hook name, too, so that instead of sending for ALL IPNs, it would only send for completed payments, for example. In that case you would use the “paypal_ipn_for_wordpress_payment_status_completed” hook instead. Of course, you can setup a variety of different hooks to handle different transaction types and payment status differently.

      Hope that helps! If you have more questions please submit an order for premium support and then we could schedule a phone/video conference with you to walk you through it.

      Reply
  2. Marco
    Marco on January 13, 2018 at 4:58 am

    Hi, thanks for plugin. Is possible not store IPN data?

    Reply
    • Andrew Angell
      Andrew Angell on January 13, 2018 at 5:05 am

      If you’re not storing the data, what exactly are you doing with the plugin? I suppose you could write a function to delete the post and then call that function after doing whatever processing you’re wanting to do.

      Reply
      • Marco
        Marco on January 13, 2018 at 5:10 am

        Yes, this is my idea 🙂
        Because I don’t wont hold all data in WP Database.
        How I can delete your post? It is a custom post_type?

        Best regards

        Reply
  3. Marco
    Marco on January 14, 2018 at 3:34 am

    Thanks.

    Reply
  4. Daniel
    Daniel on April 20, 2018 at 1:45 pm

    Hi.
    I bought “IPN Forwarder”.
    Is there a doc about the plugin?
    “Enable Smart Forwarding” ?
    I tested it with “IPN Field” -> All and with “Payment Status” -> Completed.
    In my Php file “PayPal IPN Forwarding URL” I only set a mail function to hook when the page is fired.
    I did Orders with Woocommerce. But I didn’t received nothing (only the order emails from Woocommerce)
    “Paypal IPN” list transactions are OK (Payment Status : Completed)

    Thank you.

    Reply
    • Andrew Angell
      Andrew Angell on April 22, 2018 at 4:41 pm

      We still need to get the info about Smart Forwarding added to our documentation. Sorry for the confusion on that. Basically, that lets you setup triggers to only forward the IPN to the specified URL if the conditions in the trigger you setup are met. Otherwise, that forward rule would be ignored for orders that don’t trigger that condition.

      Our plugin has an IPN History under the settings. Can you check to see what it shows for the forwarded data?

      Reply
  5. dale
    dale on August 17, 2018 at 10:01 pm

    hello recently downloaded ipn for wordpress, i was wondering, first, where might one find the predefined hooks defined, and more specifically, how does one utilize the hooks

    Reply
  6. VaughnSC
    VaughnSC on January 6, 2019 at 11:33 pm

    Hello; No mention of event order in the docs: do all these hooks fire before the post is actually inserted?

    I’m testing with the ‘catch-all’ and querying for txn_id but not getting a result on a new transaction, whereas a ‘repeat’ IPN succeeds.

    The goal is to generate an additional postmeta record so I need to supply post_id.

    Reply
← Older Comments

Submit a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.