Subscriptions v2.0: Payment Gateway Upgrade Guide

Although backward compatibility has been preserved for payment gateway APIs, Subscriptions v2.0 introduces a number of changes that relate to payment related meta data and how recurring payments are handled.

 

There are a number of updates you can make to your gateway extension’s code to support these changes and avoid deprecated notices on your customer’s sites.

If you have not already, you should read the What’s New in Subscriptions v2.0 document and Overview of Subscriptions v2.0 Architectural Changes before continuing with this document.

Items to Update

To be fully compatible with Subscriptions v2.0, you need to:

• update use of deprecated hooks
• update the location of your meta data
• add support for multiple subscriptions
• add support for admin payment method changes
• update customer facing change payment method support (if you already support it)
• use renewal orders for processing renewal payments
• make sure relevant meta data is copied from the original order to the subscription for existing orders/subscriptions on upgrade. All post meta on the original order will be copied by default by the Subscriptions upgrader, so you only need to copy meta data stored elsewhere or exclude post meta data you do not want copied, if any

Example Code: Simplify Commerce

For example code of the patches required to make a token based payment gateway fully compatible with Subscriptions v2.0, see the Simplify Commerce Subscriptions v2.0 Pull Request for WooCommerce Core.

This pull request includes annotated commits for all of the patches required by a token based payment gateway to be fully compatible with Subscriptions v2.0.

Store Meta Data on the Subscription not the Original Order

As discussed in the overview of Subscriptions v2.0’s Architectural Changes, a subscription’s meta data is no longer stored against the order created to record the purchase of that subscription. It is now stored on a separate 'shop_subscription' post type.

As a result, if your gateway stores payment related meta data, like credit card or customer tokens, it should store this against the subscription or subscriptions created during checkout and not the original order (as was previously the case).

This is also essential for adding support for the new Admin Payment Method Changes feature.

As Subscriptions will copy all post meta data stored against the 'shop_subscription' post to renewal orders (i.e. 'shop_order' posts), your gateway’s meta data will be copied to renewal orders and you can then access it on the renewal order to process the renewal payments via the 'woocommerce_scheduled_subscription_payment_{$gateway_id}' hook.

A note on upgrading: as mentioned above, all post meta on the original order will be copied by default by the Subscriptions upgrader. So migrating your code to use post meta on the subscription will work for both old and new subscriptions.

Update Deprecated Hooks

A number of hooks have been deprecated in Subscriptions v2.0, mainly due to the architectural changes.

Specifically, the following hooks have been changed in order to change the parameters passed to callbacks:

• 'scheduled_subscription_payment_{$gateway_id} has been replaced with 'woocommerce_scheduled_subscription_payment_{$gateway_id}'
• 'woocommerce_my_subscriptions_recurring_payment_method' has been replaced with 'woocommerce_my_subscriptions_payment_method'
• 'woocommerce_subscriptions_renewal_order_meta_query' has been replaced with 'wcs_resubscribe_order_created' in the case of what were previously called “parent” renewal orders and 'wcs_renewal_order_created' for orders that were previously called “child” renewal orders; and
• 'woocommerce_subscriptions_changed_failing_payment_method_{$gateway_id}' has been replaced with 'woocommerce_subscription_failing_payment_method_updated_{$gateway_id}'

You should update your use of these deprecated hooks to avoid notices and also take advantage of the extra features provided by receiving a WC_Subscription as a parameter.

Hook for Recurring Payment Method Display

By default, Subscriptions displays your payment gateway extension’s name as the payment method for a subscription; however, Subscriptions also provides an API for displaying a custom label. This can be used to provide a gateway specific and more descriptive label on the payment method. For example, the Stripe extension uses it to display the last 4 digits of the credit card used for recurring payments instead of simply Credit Card.

In Subscriptions v1.5, the filter for displaying a custom label was: 'woocommerce_my_subscriptions_recurring_payment_method'.

In Subscriptions v2.0, this has been changed to 'woocommerce_my_subscriptions_payment_method'.

The new filter passes the string displayed to describe the payment method (the same as the old filter), and then an instance of a WC_Subscription for which the string relates. This can be used to access meta data specific to that subscription.

Support for Multiple Subscriptions

Most modern payment gateways should be able to support Subscriptions v2.0’s new multiple subscriptions feature.

Specifically, if your payment gateway uses customer or credit card tokens for processing renewals, you will be able to support multiple subscriptions. Furthermore, if your payment gateway stores the meta data it uses to process automatic payments in post meta and/or user meta, adding support will be as simple as adding a 'multiple_subscriptions' value to your extension’s $supports property.

To learn more about how multiple subscriptions is implemented in Subscriptions v2.0 and to understand whether your payment gateway will be able to support it, refer to the overview of multiple subscriptions.

Support Admin Payment Method Changes

Subscriptions v2.0 introduces a new feature to allow store managers to change the payment method used on a subscription. To learn how to add support for this feature in your extension, refer to the Admin Change Payment Method Integration Guide.

Update Customer Facing Change Payment Method Support

Subscriptions v1.5 provided a customer facing process for changing the payment method.

Because it is now possible to store a subscription’s payment method meta data on the subscription instead of the original order, this process has been updated for v2.0.

To update your process, you need to:

1. declare support for the new feature, which is 'subscription_payment_method_change_customer': a new feature name has been chosen to both require an update and to differentiate between the new admin payment method change feature and the customer facing feature.
2. update your payment method’s meta data using the new 'woocommerce_subscription_failing_payment_method_updated_{$gateway_id}' hook, which passes your gateway the WC_Subscription object, instead of the old 'woocommerce_subscriptions_changed_failing_payment_method_{$gateway_id}' hook, which passed the WC_Order of the original purchase.

The code required to update Simplify Commerce can be seen in this commit to WooCommerce core on GitHub.

Use Renewal Order for Processing Scheduled Payment

As discussed in the overview of renewal order creation changes, Subscriptions v2.0 now creates the renewal order for recurring payment before triggering the scheduled subscription payment hook.

This makes it possible to use the same code for processing an initial payment as for processing a recurring payment (as the renewal order contains all essential information about the payment). It also makes it possible to record the transaction ID of the recurring payment on the renewal order by calling $renewal_order->payment_complete( $transaction_id ).

To use the renewal order for processing scheduled payments, update the code attached to the deprecated 'scheduled_subscription_payment_{$gateway_id}' action to use the new hook 'woocommerce_scheduled_subscription_renewal_{$gateway_id}' instead.

This hook will pass callbacks:

1. the amount to charge (the same as the first parameter in Subscriptions v1.5)
2. an instance of a WC_Order, which represents the pending renewal order for this payment

You can also process the renewal payment without having to worry about the associated subscription by calling $order->payment_complete( $transaction_id ) where $order is the renewal order, just as you would with a normal payment.

A Note on Tokens and Renewal Order Meta Data

You may be wondering why the 'woocommerce_scheduled_subscription_payment_{$gateway_id}' only passes callbacks the amount and a single order as a parameter, but not the WC_Subscription for which the order relates. This is to lay the foundation for batch processing renewal payments for multiple subscriptions in a single order. More generally, it also helps provide APIs that only require an understanding of WooCommerce primatives, like WC_Order, instead of Subscriptions specific objects, like WC_Subscription.

When a renewal order is generated, via wcs_create_renewal_order(), Subscriptions copies all post meta data rows stored against the 'shop_subscription' object to the new renewal order object. It is possible for extensions to opt-out their data from this process using the 'wcs_renewal_order_meta' or 'wcs_renewal_order_meta_query' hook, but it is recommended that you let your payment gateway’s token data be copied to renewal orders. This makes it possible to use only the parameters passed along with 'woocommerce_scheduled_subscription_payment_{$gateway_id}', instead of also having to use wcs_get_subscription_for_renewal_order() to access the data on the subscription.

Handling $0 Renewals

You may also (optionally) remove any code your gateway has to process $0 renewal orders/payments. Subscriptions v1.5 still called the payment gateway hook if a $0 amount was due; however, in v2.0, it no longer involves the payment gateway, and instead generates the order and processes it internally.

Test Cases

After you have updated your integration, you can confirm everything is working by running through all of the following test cases using your payment gateway as the payment method.

Tests for Subscriptions v1.5 and v2.0

• checkout with only a simple product in the cart
• checkout with only a simple subscription product in the cart
• checkout with only a simple subscription product with a sign-up fee in the cart
• checkout with only a simple subscription product with a free trial in the cart
• checkout with only a simple subscription product with a sign-up fee and free trial in the cart
• checkout with only a simple subscription product synchronized to a day in the future in the cart
• checkout with only a simple subscription product with a sign-up fee and synchronized to a day in the future in the cart
• checkout with a simple product and simple subscription product in the cart
• trigger an automatic renewal for a subscription with valid payment gateway meta data to test automatic payment success
• trigger an automatic renewal for a subscription with invalid payment gateway meta data to test automatic payment failure
• complete the manual payment process for the failed renewal and confirm that payment gateway meta data is updated correctly. Then trigger an automatic renewal after changing the payment method to ensure future renewals use the new payment gateway meta data
• test the Change Payment Method process on a subscription and confirm that payment gateway meta data is updated correctly. Then trigger an automatic renewal to ensure future renewals use the new payment gateway meta data.

Test for Subscriptions v2.0 Specific Functionality

• checkout with multiple simple subscription products with different billing periods in the cart (e.g. one subscription product renewing weekly and another renewing monthly)
• trigger an automatic renewal with working payment gateway meta data for a subscription with multiple simple subscription product line items
• checkout with a simple product and multiple simple subscription products in the cart
• (optional) if you added support for administrator payment method changes, change payment method on a subscription from the admin then trigger an automatic renewal to ensure future renewals use the new payment gateway meta data.