V3 to V4 Migration Guide

Migrating to Release 4

Release 4 is a bigger step than a normal update, so it doesn’t arrive as the usual “Update available” notice on your Plugins page — you install it using the download link and licence key from your Release 4 email. This guide walks through everything that needs doing, in order. None of it needs any coding.

If a web developer looks after your site day-to-day, this guide is worth forwarding to them.

Before you start

Release 4 needs PHP 8.2 or later and WordPress 6.0 or later. If your site is on an older version of PHP, WordPress will refuse to install it and show an error. To check, go to Tools → Site Health → Info → Server in your WordPress admin. If it needs changing, your hosting company can do it, usually from their control panel.

1. Install the update

Download the new version using the link in your recent Release 4 email, then install it the way you’d install any plugin update — deactivate the old version, upload the new zip, and reactivate. Your settings, customers, and payment history all stay exactly as they are.

2. Set up your webhook

GoCardless needs to know where to send events (payments confirmed, mandates activated, and so on). Navigate to WPdirectdebit → Settings where you’ll find your webhook URL ready to copy. Add it in your GoCardless account’s webhook settings, then copy the webhook secret GoCardless gives you back into the matching field on the Settings page. The installation guide video covers this ( https://youtu.be/VZPjcTaZdu8?si=IFKLTAgVq94ifs10 ).

3. Enter your licence key

Paste the licence key from your Release 4 email into the License Key field in Settings. If you’ve never needed one before, that’s normal — earlier versions didn’t check for one. Remember to save your settings.

Once the key is in, future Release 4 updates arrive as the usual “Update available” notice on your Plugins page, for as long as your subscription is active.

4. Review any existing forms

If you already have a live form collecting payments through GoCardless, open its feed once (Form → Settings → GoCardless) and take a careful look at the form feed settings. What’s actually changed for V4:

The old “Feed type” choice (Payment / Mandate / etc.) is now a “Payment type” dropdown. Same idea, new name — your existing choice carries across automatically, already selected when you open the feed.
Amount, billing schedule, payment description and payment day all carry across automatically too. You shouldn’t need to re-enter any of that, but just glance over it to make sure the migration is all good.
Mandate description. Check this is filled in. It’s the text your customer sees when they authorise the Direct Debit. If it’s blank when you open the feed, type it in again.
Currency. If your form set the currency from a form field rather than a fixed setting, that specific setup doesn’t carry across — Release 4 sets currency per feed, so confirm it’s showing the right one before you save.
If your form used Instant Bank Pay or PayTo, that’s now a “Collection method” option under the payment settings rather than its own feed type — check it’s still set to the instant option if that’s what you want.
If you were using the customer management, mandate management, subscription management or payment management feed types introduced in Version 3, those are gone — the new Dashboard covers all of these functions directly, so there’s nothing to migrate. Those feeds can simply be left inactive or deleted.

After opening each form, click Save. Do this for each form you have live — it’s what carries your existing setup across to Release 4’s format.

5. Review your notifications and confirmations

If you’ve customised any Gravity Forms notifications or confirmation messages around GoCardless events, they’re worth a check:

Release 4 includes a much more specific set of events to choose from when editing a notification’s Event dropdown: Mandate ready, Mandate active, Mandate cancelled, Payment confirmed, Payment paid out, Payment failed, Recurring payment created, Recurring payment create failed. These changes mean you can now respond to changes by sending more appropriate notifications. The “GoCardless Exception” notification event has been removed.

6. New for V4: reusing a customer’s mandate (optional)

Release 4 has one option that earlier versions didn’t. If you tick Reuse existing mandate in a form’s feed, a returning customer who is logged in to your website can skip the GoCardless window, and their new payment or subscription is simply added to the mandate they already have. It’s off unless you tick it, so there’s nothing to do if you don’t need it.

It’s worth knowing three things before you switch it on:

It works form by form. The tick box is part of each form’s feed, and a customer is only recognised on the same form they used before. A sign-up through one form isn’t recognised on another.
It only recognises sign-ups made after you switch it on. Customers who signed up under your old version, or under Release 4 with the box unticked, aren’t recognised yet. The first time they use the form, they go through the GoCardless window and set up a new mandate, just as they did before.
The customer has to be logged in, and the email address on the form must match the email on their WordPress account.

The full details are in the Form feed settings reference.

Notes for developers

Things that changed:

The customer ID. Release 4 stores the GoCardless customer ID in the entry meta wpdd_customer_id, where version 3 used gocardless_customer_id. Entries made under version 3 keep the old key, so code that deals with both should read both. Release 4 only stores the ID when the form’s feed has Reuse existing mandate ticked.
Reacting to events. Release 4 runs WordPress actions when GoCardless reports on a mandate or payment, once your webhook is set up: wpdd_mandate_ready, wpdd_mandate_active, wpdd_mandate_cancelled, wpdd_payment_confirmed, wpdd_payment_paid_out, wpdd_payment_failed, wpdd_subscription_created, wpdd_subscription_cancelled and wpdd_subscription_create_failed. Each passes the entry ID and, where there is one, the GoCardless ID of the mandate, payment or subscription.
Connecting to GoCardless. The version 3 way of getting a GoCardless connection, WPdirectdebit::get_instance()->get_client(), no longer exists. In Release 4, use \WPDIRECTDEBIT\Services\GoCardlessClient::create(). It returns a ready-to-use connection built from the plugin’s saved settings, or null if the site isn’t connected, so check for that, and for the class existing. It’s what the plugin itself uses throughout, though it isn’t a formally documented developer interface, so we can’t promise it will never change.
The GoCardless library. The library built into the plugin was updated from version 6 to version 8. The usual calls for customers, mandates and payments are unchanged. If your own code ships its own copy of the GoCardless library or Guzzle, remove it, or the two copies will clash.