Revision as of 08:58, 11 July 2012 (view source) John (talk | contribs) m (→‎Configuration) ← Older edit		Latest revision as of 12:18, 14 April 2024 (view source) JuanR (talk | contribs) (→‎Importing Existing Mandates)
(57 intermediate revisions by 10 users not shown)
Line 1:		Line 1:
−	==Setup==	+	== About this Module ==
−	To activate the GoCardless module in WHMCS, navigate to '''Setup > Payments > Payment Gateways''' and choose GoCardless from the Available Gateways dropdown.
−	Once activated, you can then customise the name to something more friendly such as "Direct Debit" and enter the configuration details.	+	<div class="docs-alert-success">
		+	We added this payment gateway in WHMCS 7.7.
		+	</div>
−	==Configuration==	+	[https://gocardless.com GoCardless] is a payment gateway which allows for direct debit payments to be automated electronically.
−	Within your GoCardless account navigate to the '''Developers''' tab and configure the following settings:
−	Redirect URI	+	<div class="docs-alert-info">
−	http://path/to/whmcs/modules/gateways/gocardless/redirect.php	+	<span class="title">Important</span><br />
		+	Due to GoCardless API restrictions, you must contact GoCardless support to enable the feature.
		+	</div>
		+	{{gateways
		+	| onetime = yes
		+	| recurring = yes
		+	| reversals = yes
		+	}}
		+	== Adding the GoCardless Payment Gateway ==
		+	To set up the GoCardless payment gateway in WHMCS:
		+
		+	# Go to the appropriate location for your version of WHMCS:
		+	#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
		+	#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
		+	# Click '''GoCardless'''. A GoCardless login page will appear.
		+	# Either sign up for a new account or log in to your existing account. The system will automatically configure GoCardless for you.
		+	# Optionally, enter a custom name for the gateway for each of your supported currencies.
		+	# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
		+	#In WHMCS 8.0 and later, enabling '''Charge Date Preference''' will allow the automation system to omit passing a <tt>charge_date</tt> value to GoCardless when the automation system triggers a payment attempt. This results in GoCardless starting the transaction as soon as possible.
		+	# Click '''Save Changes'''.
−	Web hooks URI	+	===Charge Date Preference===
−	http://path/to/whmcs/modules/gateways/gocardless/callback.php
		+	'''Charge Date Preference''' will determine if WHMCS passes a transaction charge date to GoCardless advising when to initiate the payment.
−	Replacing /path/to/whmcs with the location of your WHMCS installation. The Cancel URI setting can be left blank.	+	* Disabling the option will pass through either the '''Next Due Date''' from the service or the <tt>next_possible_charge_date</tt> that GoCardless sets using the <tt>charge_date</tt> function depending on which date is later.
−	==Error Messages==	+	* If you enable the option, the system will not pass a <tt>charge_date</tt> value to GoCardless and this will result in GoCardless beginning the payment process as soon as possible. In both scenarios, the payment attempt call to GoCardless will not occur until an invoice meets the invoice and payment capture attempt criteria that you set at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]'''.
−	===Client is invalid===	+
−	This means that you only have a sandbox account, a live account is required for use with this module. The live account signup link can be found on the payment gateways page within WHMCS.	+	To process the payment prior to the '''Next Due Date''' date and according to the '''Process Days Before Due''' date at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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 ===
		+
		+	GoCardless only support the following currencies:
		+
		+	* AUD
		+	* CAD
		+	* DKK
		+	* EUR
		+	* GBP
		+	* NZD
		+	* SEK
		+	* USD <div class="docs-alert-info">We added support for USD in WHMCS 7.9.</div>
		+
		+	Clients who do not use one of these currencies cannot make payments using GoCardless.
		+
		+	=== Test Mode ===
		+
		+	You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.
		+
		+	==Payment Workflow==
		+
		+	When the first payment is made, a mandate is set up with the client's bank. This typically takes a few days, so the invoice will change from '''Unpaid''' to '''Payment Pending''' status. At this point, you can view the mandate details and expected payment completion date by viewing the invoice. As soon as the mandate is set up and the first payment has cleared, the invoice's status will change to '''Paid''' and the service will be provisioned by WHMCS automatically.
		+
		+	When the renewal invoice is generated for a recurring service, a capture attempt will be made against the mandate in accordance with '''Process Days Before Due''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''. As it can take a few days for the payment to complete, we recommend a setting of '''3'''. This way, 3 days before the invoice '''Due Date''', the payment process will be initiated by the cron and the invoice status updated from '''Unpaid''' to '''Payment Pending'''. Payment should then complete on the invoice '''Due Date''' and the invoice will be marked '''Paid''' once the payment has cleared.
		+
		+	After you create a mandate, WHMCS can process renewal payments for any other services associated with the client, as long as 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.
		+
		+	To learn more, visit [[Payment Reversals]]
		+
		+	==Refunding Payments==
		+
		+	While refunds with GoCardless are not directly supported from within WHMCS, they can still be processed directly with GoCardless on a case-by-case basis through their review and approval process.
		+
		+	Please refer to the [https://support.gocardless.com/hc/en-ca/articles/210536269-Refunding-payments refunding payments] section of the GoCardless documentation.
		+
		+	== Mandates ==
		+
		+	<div class="docs-alert-success">
		+	We added these features in WHMCS 7.8.
		+	</div>
		+
		+	=== Reinstating Mandates ===
		+
		+	<div class="docs-alert-warning">
		+	Reinstating mandates requires specific permission from GoCardless.
		+	</div>
		+
		+	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:
		+
		+	# Go to the appropriate location for your version of WHMCS:
		+	#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''.
		+	#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''Manage Existing Gateways'''.
		+	#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''Manage Existing Gateways'''.
		+	# Click '''Manage Cancelled Mandates'''.
		+	# Follow the instructions in the modal that appears to reinstate a cancelled mandate.
		+
		+	=== Importing Existing Mandates ===
		+
		+	<div class="docs-alert-info">
		+	You must disable any automatically-charged mandates that you import in order to prevent possible duplicate charges.
		+	</div>
		+
		+	You can import mandates that you set up outside of WHMCS and associate them with a client.
		+
		+	To do this:
		+
		+	# Go to the appropriate location for your version of WHMCS:
		+	#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''.
		+	#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''Manage Existing Gateways'''.
		+	#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''Manage Existing Gateways'''.
		+	# Click '''Import Existing Mandates'''.
		+	# Follow the instructions in the modal that appears to import a active mandate to a specific client.
		+
		+	=== Removing Mandates ===
		+
		+	You can remove mandates by deleting the client's GoCardless [[Pay_Methods|pay method]].
		+
		+	To do this:
		+
		+	# Click on the pay method in the '''[[Clients:Summary_Tab|Summary]]''' tab of the client profile.
		+	# Click '''Delete''' to [[Clients:Summary_Tab#Removing_Card_Details|remove the pay method]] and any associated mandates.
		+
		+	== Reconfiguring Callbacks ==
		+
		+	After moving WHMCS, you must perform the following steps:
		+
		+	# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup >  Payments > Payment Gateways'''.
		+	# Click '''Configure GoCardless Account Connection'''.
		+	# Log in again using the same details.
		+
		+	This ensures that GoCardless stores and uses the new system URL and gateway callback file URL.
		+
		+	== Troubleshooting ==
		+
		+	===Access token not active===
		+
		+	You can only connect each GoCardless account to a single WHMCS 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 show an <tt>Access token not active</tt> error at '''Billing > [[Gateway Log]]'''.
		+
		+	To resolve this error, you will need to reconnect WHMCS to GoCardless by [[#Reconfiguring_Callbacks|reconfiguring callbacks]].
		+
		+	===Remote Storage "create" action did NOT provide token===
		+	This 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.
		+
		+	{{modules}}

---

Latest revision as of 12:18, 14 April 2024

About this Module

GoCardless is a payment gateway which allows for direct debit payments to be automated electronically.

Supported Features

Type	One Time	Recurring	Refunds	Reversals
3rd Party	Yes	Yes	No	Yes

Adding the GoCardless Payment Gateway

To set up the GoCardless payment gateway in WHMCS:

1. Go to the appropriate location for your version of WHMCS:
   • For WHMCS 8.0 and later, go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
   • For WHMCS 7.10 and earlier, go to Setup > Products/Services > Payment Gateways and choose All Payment Gateways.
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.
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. In WHMCS 8.0 and later, enabling Charge Date Preference will allow the automation system to omit passing a charge_date value to GoCardless when the automation system triggers a payment attempt. This results in GoCardless starting the transaction as soon as possible.
7. Click Save Changes.

Charge Date Preference


Charge Date Preference will determine if WHMCS passes a transaction charge date to GoCardless advising when to initiate the payment.

• Disabling the option will pass through either the Next Due Date from the service or the next_possible_charge_date that GoCardless sets using the charge_date function depending on which date is later.

• If you enable the option, the system will not pass a charge_date value to GoCardless and this will result in GoCardless beginning the payment process as soon as possible.
 In both scenarios, the payment attempt call to GoCardless 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

GoCardless only support the following currencies:

• AUD
• CAD
• DKK
• EUR
• GBP
• NZD
• SEK
• USD
  We added support for USD in WHMCS 7.9.

Clients who do not use one of these currencies cannot make payments using GoCardless.

Test Mode

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

Payment Workflow

When the first payment is made, a mandate is set up with the client's bank. This typically takes a few days, so the invoice will change from Unpaid to Payment Pending status. At this point, you can view the mandate details and expected payment completion date by viewing the invoice. As soon as the mandate is set up and the first payment has cleared, the invoice's status will change to Paid and the service will be provisioned by WHMCS automatically.

When the renewal invoice is generated for a recurring service, a capture attempt will be made against the mandate in accordance with Process Days Before Due in Configuration () > System Settings > Automation Settings or, prior to WHMCS 8.0, Setup > Automation Settings. As it can take a few days for the payment to complete, we recommend a setting of 3. This way, 3 days before the invoice Due Date, the payment process will be initiated by the cron and the invoice status updated from Unpaid to Payment Pending. Payment should then complete on the invoice Due Date and the invoice will be marked Paid once the payment has cleared.

After you create a mandate, WHMCS can process renewal payments for any other services associated with the client, as long as 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.

To learn more, visit Payment Reversals

Refunding Payments

While refunds with GoCardless are not directly supported from within WHMCS, they can still be processed directly with GoCardless on a case-by-case basis through their review and approval process.

Please refer to the refunding payments section of the GoCardless documentation.

Mandates

Reinstating Mandates

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 the appropriate location for your version of WHMCS:
   • For WHMCS 8.6 and later, go to Configuration () > System Settings > Payment Gateways.
   • For WHMCS 8.0 and later, go to Configuration () > System Settings > Payment Gateways and choose Manage Existing Gateways.
   • For WHMCS 7.10 and earlier, go to Setup > Products/Services > Payment Gateways and choose Manage Existing Gateways.
2. Click Manage Cancelled Mandates.
3. Follow the instructions in the modal that appears to reinstate a cancelled mandate.

Importing Existing Mandates

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

To do this:

1. Go to the appropriate location for your version of WHMCS:
   • For WHMCS 8.6 and later, go to Configuration () > System Settings > Payment Gateways.
   • For WHMCS 8.0 and later, go to Configuration () > System Settings > Payment Gateways and choose Manage Existing Gateways.
   • For WHMCS 7.10 and earlier, go to Setup > Products/Services > Payment Gateways and choose Manage Existing Gateways.
2. Click Import Existing Mandates.
3. Follow the instructions in the modal that appears to import a 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 or, prior to WHMCS 8.0, Setup > Payments > 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

Access token not active

You can only connect each GoCardless account to a single WHMCS 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 show an Access token not active error at Billing > Gateway Log.

To resolve this error, you will need to reconnect WHMCS to GoCardless by reconfiguring callbacks.

Remote Storage "create" action did NOT provide token

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