GoCardless

GoCardless is a payment gateway that automates electronic direct debit payments.

Supported Features

Type: Third-Party

One-TimeRecurringRefundsReversals
✖️
3D SecureRemote Update CardRemote Delete CardAddPayMethod API
✖️✖️✖️✖️

Adding the GoCardless Payment Gateway

To set up the GoCardless payment gateway in WHMCS:

  1. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
  2. Click GoCardless. A GoCardless login page will appear.
  3. Either sign up for a new account or log in to your existing account. The system will automatically configure GoCardless for you.
    Due to GoCardless API restrictions, you must contact GoCardless support to enable this feature.
  4. Optionally, enter a custom name for the gateway for each of your supported currencies.
  5. Check Show on Order Form to display this payment method in the Client Area during checkout.
  6. Enable Charge Date Preference to omit the charge_date value when the automation system triggers a payment attempt. This results in GoCardless starting the transaction as soon as possible. For more information, see Charge Date Preference below.
  7. Click Save Changes.

Charge Date Preference

Charge Date Preference determines whether WHMCS passes a transaction charge date to GoCardless advising when to initiate the payment.

  • Disabling Charge Date Preference passes the Next Due Date value from the service or the next_possible_charge_date value that GoCardless sets using the charge_date function, whichever is later.
  • If you enable Charge Date Preference, the system will not pass a date to GoCardless and GoCardless will begin the payment process as soon as possible.


In both scenarios, the payment attempt will not occur until an invoice meets the invoice and payment capture attempt criteria that you set at Configuration () > System Settings > Automation Settings.

To process the payment prior to the Next Due Date date and according to the Process Days Before Due date at Configuration () > System Settings > Automation Settings, enable this setting. If you do not, the system may attempt the payment on or after the Next Due Date date.

Supported Currencies

Clients must use a supported currency to make payments using GoCardless. GoCardless only support the following currencies:

  • AUD
  • CAD
  • DKK
  • EUR
  • GBP
  • NZD
  • SEK
  • USD

Test Mode

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration.

Payment Workflow

At the time of the first payment, the system sets up a mandate with the client’s bank. This typically requires a few days, and the invoice status will change from Unpaid to Payment Pending. During this step, you can view the mandate details and expected payment completion date by viewing the invoice. When the mandate is ready and the first payment clears, the invoice’s status will change to Paid and WHMCS will provision the service automatically.

When the system generates a renewal invoice for a recurring service, it will attempt capture against the mandate in accordance with the Process Days Before Due setting in Configuration () > System Settings > Automation Settings. (We recommend setting Process Days Before Due to 3.) This will cause the system to initiate the payment process and update the invoice status from Unpaid to Payment Pending. Payment will process on the invoice due date and the invoice will update to Paid after the payment clears.

After you create a mandate, WHMCS can process renewal payments for any of the client’s other services if they also use the GoCardless gateway.

The system redirects clients to GoCardless to enter their bank details when setting up a mandate. Then, GoCardless returns them to WHMCS after the setup is complete. The system submits personal bank information directly to GoCardless and never stores it in your local WHMCS installation.

Reversed Payments

The Direct Debit Guarantee scheme allows the payee to file a claim for any payment taken in error. WHMCS will monitor for charged_back events from GoCardless and will automatically process these as appropriate.

For more information, see Payment Reversals.

Refunding Payments

WHMCS does not directly support refunds through GoCardless, but you can process them directly through GoCardless on a case-by-case basis using their review and approval process.

For more information, see GoCardless’s Refunds documentation.

Mandates

Reinstating Mandates

Reinstating mandates requires specific permission from GoCardless.

When a mandate has been accidentally cancelled, WHMCS can initiate steps to reinstate the mandate without having the client set it up again.

To do this:

  1. Go to Configuration () > System Settings > Payment Gateways.
  2. In WHMCS 8.5 and earlier, click the Manage Existing Gateways tab.
  3. Click Manage Cancelled Mandates.
  4. Follow the displayed instructions to reinstate a cancelled mandate.

Importing Existing Mandates

You must disable any automatically-charged mandates that you import in order to prevent possible duplicate charges.

You can import mandates that you set up outside of WHMCS and associate them with a client.

To do this:

  1. Go to Configuration () > System Settings > Payment Gateways.
  2. In WHMCS 8.5 and earlier, click the Manage Existing Gateways tab.
  3. Click Import Existing Mandates.
  4. Follow the displayed instructions to import an active mandate to a specific client.

Removing Mandates

You can remove mandates by deleting the client’s GoCardless pay method.

To do this:

  1. Click on the pay method in the Summary tab of the client profile.
  2. Click Delete to remove the pay method and any associated mandates.

Reconfiguring Callbacks

After moving WHMCS, you must perform the following steps:

  1. Go to Configuration () > System Settings > Payment Gateways.
  2. Click Configure GoCardless Account Connection.
  3. Log in again using the same details.

This ensures that GoCardless stores and uses the new system URL and gateway callback file URL.

Troubleshooting

You may encounter the following errors when using GoCardless:

ErrorDescriptionRecommended Solution
Access token not activeYou can only connect each GoCardless account to a single WHMCS installation at a time. If you connected the GoCardless account to multiple WHMCS installations, only the last installation that you connected will function correctly. Previously-connected WHMCS installations will log this error at Billing > Gateway Log.To resolve this error, reconnect WHMCS to GoCardless by reconfiguring callbacks.
Remote Storage "create" action did NOT provide tokenThis error indicates that the GoCardless account does not have access to the required API endpoint. Due to GoCardless API restrictions, you must contact GoCardless support to enable the feature for your account.Use a GoCardless Pro or GoCardless Enterprise account to configure the payment gateway.

Last modified: September 23, 2024