INTRODUCTION
------------
This module is provided by Seamless-CMS which is a [partner of GoCardless](https://gocardless.com/partners/category/e-commerce).
It integrates the Ubercart e-commerce suite with the GoCardless online payment service. Sites that implement the module are 'clients' of Seamless-CMS, which generates GoCardless payments and debit mandates in conjunction with the client site.
Ubercart GoCardless Client enables customers to checkout and make Instant payments using open banking protocol, and/or create debit mandates for generating recurring payments.
The **big** advantage with GoCardless is that it is generally [cheaper](https://gocardless.com/pricing/) than credit/debit card payment services. Fees in the UK are 1% + 20p, compared with Paypal for example which is 3.4% + a flat fee.
Each product in your store is individually configured to use either Instant payments, or one of the two recurring payment types: "One-off" payments, or Subscription payments.
Instant payments are single payments created upon checkout by GoCardless using open banking protocol and do not require a debit mandate. Open banking does not use credit/debit cards but the experience is similar to credit card services in that the customer is required to provide their bank details, and to verify the bank account. Instant Payments are a newly introduced feature from GoCardless, and are currently only available to customers with British or German bank accounts.
Subscription and One-off payments both require a direct debit mandate, which is created by GoCardless upon checkout.
Subscriptions are recurring payments that are created automatically by GoCardless according to the rules that you set for the product. Subscriptions 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 are created when your website instructs GoCardless to do so, and are more flexible than Subscription payments. This allows you to charge your end customers ad-hoc amounts. The module allows One-off payment products to be configured so that your website will automatically generate payments for them according to a schedule.
The main disadvantage with debit payments compared with Instant payments, is that it takes several days for them to complete, following an instruction from GoCardless to the bank to create a new mandate, and payment.
As a partner of GoCardless, Seamless-CMS receives a percentage of any revenue collected from payments. This arrangement does not cost client sites, or end customers any extra, and it is intended that the income derived here will make the development and maintenance of the module sustainable.
MODULE FEATURES
---------------
* Instant Payment checkouts using open banking protocol
* Subscriptions for automatic recurring payments
* One-off payments for client-side ad-hoc payment creation
* Fully configurable pre-defined recurrence rules on a per product basis
* A pre-defined product attribute to allow customers to choose their own recurrence preferences
* Client-side scheduling for recurring One-off payments
* No libraries - easy installation
* Available in an expanding range of currencies and countries - even if your store only uses one currency
* Tools for managing subscriptions and one-off payments within existing orders / mandates
* A range of hooks to allow other modules to alter or react to events, such as mandate or payment creation
* GoCardless webhooks providing complete integration with site and customer mandates
REQUIREMENTS
------------
* An SSL certificate (https) is required to use the module in live mode (but not in sandbox mode).
* This module requires that the following modules are also enabled:
- [Ubercart Payment](https://backdropcms.org/project/ubercart)
- [Ubercart Product Attibutes](https://backdropcms.org/project/ubercart)
PRODUCT PAYMENT TYPES
---------------------
Each product in your store is individually configured to use either Instant
payments, or one of the two recurring payment types: One-off payments, or
Subscription payments.
Instant payments are single payments created upon checkout by GoCardless using
open banking protocol and do not require a debit mandate. Open banking does not
require credit/debit cards but the experience is similar to other online
payment services in that the customer is required to provide their bank
details, and to verify the bank account.
Subscription and One-off payments both require a direct debit mandate, which is
created by GoCardless upon checkout. Subscriptions are recurring payments that
are created automatically by GoCardless according to the rules that you set for
the product. One-off payments are (recurring) payments that are created
automatically when your website instructs GoCardless to do so, and are more
flexible than Subscription payments. Debit payments take several days to
complete following an instruction from GoCardless to the bank to create the
payment.
Instant payments are only created if none of the products in a cart are using
recurrence rules, or if they are One-off payments that are configured to
'Raise payment immediately' upon checkout. Instant payments are currently only
available for customers with British or German bank accounts. If it is not
possible to create an Instant payment upon checkout, a debit mandate will be
created instead, and the product will be paid for with a One-off payment.
DIFFERENCES FROM DRUPAL 7
-------------------------
- The module is basically the same as the Drupal 7.x.2.x version except for
some minor code improvements.
INSTALLATION
------------
* Install this module using the official Backdrop CMS instructions at
https://docs.backdropcms.org/documentation/extend-with-modules.
CONFIGURATION
-------------
* Visit the payment method configuration page under Administration > Store > Configuration >
Payment methods > GoCardless (/admin/store/settings/payment/method/gc_client)
and enter the required information.
* Before you can use your site with GoCardless you need to 'Connect' as a
client of Seamless-CMS. Do this from the payment method configuration page.
Click 'Connect SANDBOX' and you will be taken through the GoCardless
"OAuth Flow". Upon return to the site you should be connected.
You will be provided with a 30 byte Webhook Secret which you must set
in your GoCardless account. You also need to go through the GoCardless
'onboarding' process in order to verify your account and receive any
payouts that you have generated. (You do not need to 'onboard' with a sandbox account.)
* Ensure that the Payment method pane is enabled at Administration > Store > Configuration >
Payment methods (/admin/store/settings/payment/method)
* Additional settings are provided for each specific Ubercart product. These
are configured by clicking the GoCardless Settings vertical tab, at the
bottom of the product's Edit form.
* The module provides a Payment Interval attribute, with four presets:
weekly, fortnightly, monthly and yearly. Enabling this will allow your
customers to choose the payment plan of their choice. Alternatively you can
configure a product to a specific fixed payment interval.
* Several hooks are provided to enable other modules to interact with this
one at key moments, such as before setting up a new debit mandate,
or before creating a payment, or after receiving a webhook from GoCardless.
More information on using these is provided in uc_gc_client.api.php.
INTERNATIONAL PAYMENTS
----------------------
GoCardless is an expanding [international payment system](https://gocardless.com/international-payments), and is currently available in 8 currencies and 30+ countries. Currencies supported are GBP, EUR, USD, SEK, AUD, NZD, DKK and CAD.
According to GoCardless their international payment system is [75% cheaper](https://gocardless.com/blog/how-much-do-international-payments-really-cost) than Paypal, and is also considerable cheaper than Stripe.
The module allows you to collect payments in multiple currencies even if your store only uses a single currency.
You can use GoCardless to create payments in a growing number of currencies.
To use international payments, you must contact help@gocardless.com and
request that they enable the required region(s), so that you can use the
relevant debit schemes. Instructions on how to do this are at:
https://support.gocardless.com/hc/en-gb/articles/115002833785-Collecting-from-multiple-regions.
Alternatively you can request GoCardless to enable FX payment for your account,
which will enable you to collect payments in the whole range of GoCardless
currencies if you want. (After you have connected with GoCardless in the payment method configuration page, a message will be displayed telling you if FX payment is enabled for your account or not. For new accounts it is enabled by default.)
Having done this, check "Create payments in foreign currencies" on the
GoCardless payment method configuration page.
After enabling foreign currencies, tell Ubercart which countries GoCardless
can use at: Administration > Store > Configuration > Countries > GoCardless (/admin/store/settings/countries/gc_client).
You should only enable countries here that use a currency that is enabled
for your GoCardless account (via FX payments or otherwise).
When checking out via GoCardless, the countries that are available for the
billing and delivery addresses will be filtered to only include those selected
above. After redirection to GoCardless the customer is required to provide
details of a bank that is located in the specified country, and if a debit
mandate is created it will use the relevant "scheme" (i.e. BACS, SEPA, etc.).
If the customer is paying with a foreign currency, then the module will obtain
the latest up to date, real exchange rates from the GoCardless API, and
automatically alter the price for the product. For example a customer with a
French bank account purchases a £10 product from a British store and pays €12
after the price has been adjusted using the latest real exchange rates.
If you are using other payment methods in addition to GoCardless, you must
enable and configure the Ubercart Ajax Administration module, to ensure that the correct countries
are listed in the Delivery and Billing panes at checkout.
After enabling uc_ajax go to Administration > Store > Configuration > Checkout > Ajax (/admin/store/settings/checkout/ajax)
1. Add 'Payment method' as a Triggering form element
2. Select Delivery information and Billing information as Panes to update
3. Submit
You must also make sure that GoCardless isn't the default payment method, because it
needs to be actively selected in checkout in order to filter the correct
countries. (The default payment method is the first enabled method in the list
at Administration > Store > Configuration > Payment methods.)
ISSUES
------
Bugs and feature requests should be reported in the project's [Issue Queue](https://github.com/backdrop-contrib/uc_gc_client/issues).
Other known issues:
1. Connecting with GoCardless: There is a known issue with the cURL HTTP
Request module, that causes authentication to fail when this module
attempts to connect.
2. This module does not work properly if you are developing your site on localhost. In order
to for it to work you need a sandbox environment that is on the internet
and has a domain name.
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, we will generate a modest income stream, which helps to ensure that the module
is properly maintained, and that we able to respond efficiently to security
threats, issues, and feature requests. So please help spread the word!
Credits
-------
- Ported to Backdrop CMS by [Rob Squires](https://github.com/roblog).
- Originally written for Drupal by [Rob Squires](https://github.com/roblog).
License
-------
This project is GPL v2 software.
See the LICENSE.txt file that ships with the module for complete text.
