CONTENTS OF THIS FILE
---------------------
* Introduction
* Requirements
* Installation
* Configuration
* International payments
* Shipping
* Known Issues
* Seamless-CMS
* Maintainers
INTRODUCTION
------------
The Commerce GoCardless Client module provides an integration with Drupal
Commerce, and GoCardless.com. The module integrates into Commerce like any
other payment service, and allows customers to create a direct debit
mandate for paying for products upon checking out. GoCardless is very
competitive compared with other payment services and charges 1% on
transactions, with a minimum of 20p in the UK, and a similar amount in other
currencies.
There are two kinds of payment service available from GoCardless: Subscriptions
and 'One-off' Payments.
Subscriptions are automatic recurring payments, and work well for users
that want to take the same payment on a regular basis (for instance £5 per
week, or £20 on the first of each month).
One-off Payments allow the client site to trigger a payment against a
direct debit mandate at any time with the API. This allows you to charge
your end customers ad-hoc amounts. One-off payments offer more flexibility than
Subscriptions, and the module provides means for them to be scheduled
client-side by your web site, so you can provide the flexibility of one-off
payments, within a recurring payment schedule.
Commerce Product Variations are individually configurred to use either
Subscription or One-off payment recurrence rules. An order item does not have
to have recurrence rules set in order to be included in a GoCardless checkout.
Non Gocardless-enabled items will automatically be classed as One-off Payment
type, and a single payment will be created immediately at checkout, with no
recurrence scheduled.
* For a full description of the module, visit the project page:
https://drupal.org/project/commerc_gc_client
* To submit bug reports and feature suggestions, or to track changes:
https://drupal.org/project/issues/commerce_gc_client
REQUIREMENTS
------------
* An SSL certificate (https) is required in order to use the module in
live mode although it is not required for sandbox.
* This module requires the following modules:
- Commerce Payment
- Commerce Product
- Commerce Cart
INSTALLATION
------------
* Install as you would normally install a contributed Drupal module. Visit:
https://www.drupal.org/docs/8/extending-drupal-8 for further information.
CONFIGURATION
-------------
* Install and enable the Commerce payment service in the normal way:
admin >> commerce >> config >> payment-gateways.
* Before you can use your site with GoCardless you need to 'Connect' as a
client of Seamless CMS. This is initiated from the payment gateway's
configuration page. To do this, click on the 'Connect' button and follow
the steps. You will be redirected to GoCardless.com. If you do not have an
account with GoCardless at this point, you will be required to create one.
After this you will be redirected a second time, to Seamless-CMS.co.uk as
the final stage in the Connection process, before being returned back to
your site.
It is also important that you set up your GoCardless account properly so
that you will receive webhooks. Instructions for this are included on the
payment gateway configurration form.
* The module ships with 'GoCardless' Product, and Product Variation types.
You do not have to use these but they provide an example of how to
configure your store to use the module. Each product variation type has a
checkbox: 'Use GoCardless recurrence rules ..'. When you enable
this for a specific type, a set of GoCardless recurrence options are
provided in the Edit form for product variations of this type.
* Product variations are individually configurred, either as Subscription of
One-off payments, along with the required recurrence rules. An order item
does not need to be using recurrence rules to be included in a GoCardless
checkout. Such items will be treated as 'One-off payment' types, with a
single payment being created immediately upon checkout, and no recurring
payments scheduled.
* Several 'Events' are provided to enable other modules to interact at key
points, such as before setting up a new direct debit mandate, before
creating a payment, or after receiving a webhook from GoCardless.
More information on using these is provided in GoCardlessEvents.php.
INTERNATIONAL PAYMENTS
----------------------
GoCardless can be used with an expanding range of currencies, and even if
your store only uses one currency you can still use the whole range of
GoCardless currencies if you wish, to increase your market. So for example
if your product's currency is GBP (British Pound), and your customer is from,
an EU nation, then the direct debit mandate can be created using the SEPA
scheme, in which case payments will be created in EUR. In these circumstances,
the module uses a third party service (fixer.io) to automatically calculate
the amount of each recurring payment using up to date currency conversion
rates. (Note that in order for this example to work you would need to contact
GoCardless and request that they enable the SEPA scheme for your merchant
account.)
Although it will work, it is not recommended to use this module with Commerce
Currency Resolver. The problem is that in the above example, CCR will convert
the GBP price of the product into EUR, at current exchange rates, so all
future recurring payments will be created for the same amoung in EUR, and
will not reflect fluctuations in exchange rates. If possible it is better to
use the solution provided by this module, where the product's price remains
as GBP, but the EUR price is recalculated with each recurring payment, using
the latest exchange rates.
There is a form at admin >> commerce >> config >> currencies > gocardless.
Use this to select which currencies you have enabled with GoCardless.com.
COMMERCE SHIPPING MODULE
------------------------
GoCardless Client allows you to check out with a range of products in the
cart, and in such cases, all products are paid for using the same direct
debit mandate. However since products are likely to be a mixture of One-off,
and Subscription payments, and to have different recurrance rules, this
creates issues for shipping costs. To manage this, during checkout, the
proportion of the total shipping cost for the order is calculated for each
order item, and saved for future use when creating payments for items.
Upon completion of checkout, it is possible to access the GoCardless details
for the order, and there is form where you can review and alter the
proportion of the order's total shipping cost for each order item.
The module provides an 'Event', which can be hooked into to calculate the
proportion of the shipping for each order item. The module also includes an
Event Subscriber that works out of the box, for 'flat_rate', and
'flat_rate_per_item' shipment plugins. Developers can use this as a model,
and override it with your own event subscriber, if you need more bespoke
functionality, or need this to work with different shipment plugins.
KNOWN ISSUES
------------
The module provides information on the GoCardless mandate for an order, in
it's 'View' page (in both Admin and User view modes). A mandate cancellation
link is also available. The extra information is included in a form 'Detail',
but at the moment this Detail is not available out of the box. Use the patch
at https://www.drupal.org/project/commerce/issues/2915559 to make this work in
Admin view mode. There is currently no patch for the User view mode, but
applying the same code in the patch for the relevant template for the User
view mode also works.
SEAMLESS-CMS
------------
Sites that implement the module are 'clients' of https://seamless-cms.co.uk,
which handles the management of direct debit mandates and payments with
GoCardless on behalf of the client site. The reason that the module works
via Seamless-CMS, rather than directly with GoCardless is that Seamless
is a partner of GoCardless.com, and as such, generates an income of 10% of
GoCardless' fees (0.1%) on each transaction). I hope that by building up this
business, I can develop a modest income stream to ensure that the module is
well maintained, and I can respond efficiently to security issues, support,
and feature requests. So please give the module a try and encourage others to
do the same.
MAINTAINERS
-----------
Current maintainer:
* Rob Squires (roblog) - https://www.drupal.org/u/roblog
