Commerce installation on Drupal 7

CONTENTS OF THIS FILE
---------------------

* Introduction
* Requirements
* Recommended modules
* Installation
* Configuration
* International payments
* Issues
* FAQ
* Maintainers


INTRODUCTION
------------

The Commerce GoCardless Client module provides an integration with Drupal
Commerce, and GoCardless.com. 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 module integrates into Commerce like any other payment service module,
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. The module also enables one-off payments
to be scheduled client-side.

* 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 UI
- Commerce Product
- Commerce Cart


RECOMMENDED MODULES
-------------------

* Date Popup (https://www.drupal.org/project/date):
This module ships with the Date module and when enabled it provides a
user friendly popup widget for date fields.
* Fieldset Helper (https://www.drupal.org/project/fieldset_helper):
Provides enhanced user experience for customers and administrators
by remembering the state of a Drupal collapsible fieldsets.


INSTALLATION
------------

* Install as you would normally install a contributed Drupal module. Visit:
https://drupal.org/documentation/install/modules-themes/modules-7
for further information.


CONFIGURATION
-------------

* Install and enable the Commerce payment service in the normal way:
admin >> commerce >> config >> payment-methods

* Before you can use your site with GoCardless you need to 'Connect' as a
client of Seamless CMS. This is initiated from the payment method'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.

* Ensure that the Payment method pane is enabled at
admin >> commerce >> config >> checkout

* The module ships with a 'GoCardless' product type:
admin >> commerce >> products >> types >> product-gocardless

You do not have to use this but it provides an example of how to
configure your store to use the module. Each product type had a checkbox:
'Use GoCardless recurrence rules with this product type'. When you enable
this for a specific product type, a set of GoCardless rucurrence
configuration options are provided for the products in their Edit forms.

* The module provides a 'GoCardless payment interval' field, which is
automatically enabled in the GoCardless product type upon installation:
admin >> commerce >> /products >> types >> product-gocardless >> fields

This field can be added (or removed) to other product types in the usual
way using the Manage Fields UI. The GoCardless recurrence rules allow you
to define the interval length and unit between payments for a product.
Alternatively the field can be used to allow customers to select the
payment interval as a product attribute, whilst they are purchasing
the product. The field comes with preset values, e.g. 2 weekly, 1 monthly,
etc. Using the field UI you can add values of your own choice.

A product does not need to be using recurrence rules in order to be included
in a GoCardless order. Such products will be treated as 'One-off payment'
types, with a single payment being created immediately upon checkout, and
no recurring payments scheduled.

* When a customer checks out with GoCardless, all the products in their
cart are paid for using the same direct debit mandate. Since a mandate is
only able to use a single currency it is important that all the product's
in an order use the same currency. The module therefore provides a rule,
'Validate GoCardless cart items', which ensures that all products added
to the cart have the same currency. If your store is using multiple
currencies it is recommended that you leave this rule enabled.

* Several hooks are provided to enable other modules to interact with this
one at key moments, such as before setting up a new direct debit mandate,
or before creating a payment, or after receiving a webhook from GoCardless.
More information on using these is provided in commerce_gc_client.api.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 store's currency is GBP (British Pound), and the customer is French,
then the direct debit mandate can be created using the SEPA scheme, in which
case payments will be created in Euro. In these circumstances, the module uses
a third party service (fixer.io) to automatically calculate the amount of the
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.)


SHIPPING
--------
The module allows you to check out with a range of products in the cart. 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. These need to be attributed accordingly to each product so
that when a subscription or a payment is created for each product the correct
amount is provided.

The module ships with a solution to this problem, utilising the Flat Rate
shipping module. The GoCardless product type is pre-installed with a field
called 'Shipping Cost'. (This field is also available to other product types.)
This field works in conjunction with a rule, called 'Handle GoCardless
shipping using field_shipping_cost', which is available when the Commerce
Shipping module is enabled. This rule is used to record the shipping cost of
each product in the cart at checkout, so that when recurring payments are
created for the product in the future, the amount will include an attributed
shipping cost amount.


FAQ
---

Q: Where can I get an affordable SSL certificate for my site?

A: SSL certificates are available for free from https://www.sslforfree.com.
Let's Encrypt is the first free and open Certificate Authority. Since they
are a charity it is recommended that you make a small donation to their
service to help make it sustainable.


Q: Why not integrate directly with GoCardless rather than as a client of
Seamless CMS?

A: It is perfectly possible to do this and GoCardless provide very good
instructions for using their API. However, as a partner of GoCardless,
Seamless CMS generates an income of 10% of GoCardless' fees
(0.1% of each transaction). It is intended that by building up this
business, I can develop a modest income stream to ensure that the module
is properly maintained, and I am able to respond efficiently to security
threats, issues, and feature requests. So please help spread the word!


MAINTAINERS
-----------

Current maintainers:
* Rob Squires (roblog) - https://www.drupal.org/u/roblog