# GoCardless Module

https://docs.wisecp.com/en/gocardless-module

Collect one-off payments straight from your client's bank account with GoCardless, on a mandate the client authorises once.

## Reaching the Screen

Go to **Settings → Financial → Payment Gateways**, open **All Modules** and click the GoCardless card: `{admin}/modules/payment?module=GoCardless`

Ticking **Status** and saving lists the method on the payment step. Use [Payment Gateways](https://docs.wisecp.com/en/payment-modules) to order the methods clients see.

## What Is on the Screen

The card holds your access token, the sandbox switch, the webhook secret and the shared gateway settings.

GoCardless collects by direct debit. The client is sent to a GoCardless page and authorises a mandate on their bank account once; later payments reuse that mandate without asking again.

A bank debit is not instant. The payment is created as pending and the invoice waits at **Payment Pending**. In the current version the confirmation from GoCardless does not settle the invoice; you mark it paid yourself, see Tasks. Refunds go through your GoCardless dashboard. Stored cards, automatic payments from a saved card and installments are not supported.

## Before You Configure It

- A GoCardless account. Testing needs a separate sandbox account, opened at `manage-sandbox.gocardless.com`.
- An access token created under **Developers → API settings** in that same environment. Only an administrator can create one.
- A webhook endpoint created in the same account, so you have a secret to enter here.
- A currency and client country GoCardless supports for direct debit. If your install prices in another currency, set **Converting Currency**.

## Fields

- **Status**: Turns the module on. While it is off the other fields stay locked and clients are never offered the method.
- **Access Token**: Required. The access token from your GoCardless developer panel. A sandbox token only works with **Sandbox Mode** ticked.
- **Sandbox Mode**: Sends every request to the GoCardless sandbox instead of the live service. It arrives unticked.
- **Webhook Secret**: The secret GoCardless shows on the webhook endpoint you created. This version stores the value without using it: the signature on an incoming notification is not compared against it.

Commission, converting currency, accepted amount range and country lists behave the same on every gateway; see [Payment Gateways](https://docs.wisecp.com/en/payment-modules). **Callback URL**, **Success URL** and **Failed URL** cannot be edited; the callback address is the one you register as a webhook.

## Tasks

### Connect your GoCardless account

1. In your sandbox dashboard open **Developers → API settings**, click **Create** in the top right and choose **Access token**. Name it, give it read-write access and copy it: the token is shown once.
2. Open the GoCardless card under **All Modules** and tick **Status**.
3. Paste your sandbox token into **Access Token** and tick **Sandbox Mode**.
4. Click **Save Changes**. The method now appears on the payment step.

### Register the notification address

1. Copy the **Callback URL** from the module card.
2. On the GoCardless **Developers** page click **Create → Webhook endpoint**, paste that address as the URL and name the endpoint.
3. Open the new endpoint in the list and copy its secret into **Webhook Secret**, then click **Save Changes**. GoCardless sends every event; this module reads `payments` events with the action `confirmed`.
4. In the current version the notification cannot be matched to the invoice, so it does not close the invoice yet; see the next task.

### Run a test payment

1. Place a small order as a client and choose GoCardless on the payment step.
2. Complete the mandate on the GoCardless page with its test bank details.
3. The client returns and the payment waits for clearance; the invoice moves to **Payment Pending** meanwhile.
4. Once the sandbox shows the payment as confirmed, open the invoice in [Invoice Detail](https://docs.wisecp.com/en/invoice-detail-overview) and mark it paid. That activates the order.

### Refund a payment

1. Open the invoice from [Invoice Detail](https://docs.wisecp.com/en/invoice-detail-overview).
2. Set its status to refunded, choose **Add as expense** or **Add as account credit** as the refund method and confirm. An invoice you marked paid yourself has no payment record behind it, so **Refund via payment gateway** has nothing to send.
3. Return the money from your GoCardless dashboard.

## Things to Watch

> **The order waits for the bank and for you**
> 
> A direct debit clears in days, not seconds. Until you mark the invoice paid it sits at **Payment Pending** and the service is not activated. Check your GoCardless dashboard for confirmed payments, and tell clients who expect instant delivery to pay another way.

> **Sandbox and live are separate accounts**
> 
> A sandbox token collects nothing, and a live token fails while **Sandbox Mode** is ticked. Change the token and the switch together, and create a webhook on the live account as well. A sandbox mandate stays on the client record and is reused instead of asked for again. Do not take live payments from the accounts you tested with.

> **Renewable orders cannot be paid**
> 
> An order with renewable items opens a choice screen: pay once, or start an agreement. Its buttons do nothing in this version, so the client stops there. Offer another method for those orders.

## Required Privileges

**Payment Module Settings** (`MODULES_PAYMENT_SETTINGS`) is required.

## Related Articles

- [Payment Gateways](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail](https://docs.wisecp.com/en/invoice-detail-overview)