# Connecting GoCardless

> Connecting to GoCardless is an OAuth process. It requires you to log into GoCardless, which then shares a security token with us. To complete this you need a Go

Connecting to GoCardless is an OAuth process. It requires you to log into
GoCardless, which then shares a security token with us. To complete this you need a
GoCardless login with **administrator access** on your GoCardless account.

1. When prompted, select **Connect GoCardless** to log in to your GoCardless
   account.

   ![Connect GoCardless dialog](/_astro/cdn/bfd64132ab/connect-1.png)

2. If you have not recently been logged into GoCardless you will be prompted with a
   login screen. Log in as an administrator of the account.

   :::note[Tip]
   On the GoCardless authorisation screen, the application requesting access appears as **"Payments"**.
   :::

   ![GoCardless OAuth login screen](/_astro/cdn/8ec4678fe0/connect-2.png)

3. After login you are returned to a configuration screen. The connection is tested
   and you are shown a green **"Connected to GoCardless"** message. If there is an
   error with the connection, an error message is shown instead.

   ![Connected to GoCardless configuration screen](/_astro/cdn/eed8b3c46a/connect-3.png)

## Connection options

Our integration with GoCardless offers several options:

- **Enable refunds:** You must contact GoCardless to enable refunds on your
  account. Once they have, check this box to be able to use refunds. See
  [Refunding payments](https://support.gocardless.com/hc/en-gb/articles/210536269-Refunding-payments)
  in the GoCardless support centre.
- **Enable custom references:** If you have this feature enabled on your GoCardless
  account, check this box to use custom references. The `transaction.reference`
  (for example `REF-00010012`) is mapped into the GoCardless reference field. See
  [Custom payment references](https://support.gocardless.com/hc/en-gb/articles/115003660445-Custom-payment-references).
- **Enable offline mandates:** Lets staff set up a Bacs, SEPA or ACH Direct Debit
  mandate and take the first payment on the customer's behalf, for example over the
  phone (MOTO), using bank details the customer gives them. Offline mandates are
  available for GBP, EUR and USD.
- **Enable Instant Bank Pay (UK & EU only):** If you have this feature enabled on
  your GoCardless account, check this box to use it — see
  [Instant Bank Pay](#instant-bank-pay) below.
- **Use bank reason code as decline authorization:** When a transaction is
  declined, by default a user-friendly GoCardless interpretation of the decline
  reason is returned in the `authorization` field of the transaction. Select this
  checkbox to instead return the underlying scheme decline reason code (for example
  Bacs `ARUDD0`, ACH `R01`).
- **Retry failed transactions:** GoCardless does not follow the same retry
  processing as other gateways, due to nuances in how it works. There are three
  options:
  - **Disabled:** No automated retries.
  - **Enabled:** Automated retries, as soon as possible (typically 3 days to
    process). You can choose which declined transactions get retried — from
    **Insufficient funds** and **Refer to payer** — and set the **Number of retries**
    (between 1 and 3).
  - **Success +:** If you have this feature enabled on your GoCardless account,
    GoCardless runs an optimised retry process based on its own data (for example
    aligning retries with pay days).

## Instant Bank Pay

Instant Bank Pay and Direct Debit serve different purposes. Instant Bank Pay is a
single, pay-now bank transfer that confirms payment immediately at the point of
checkout: the customer authorises a one-off push payment from their bank, giving
you real-time confirmation that funds have been approved. Direct Debit, by
contrast, is a mandate-based method designed for future payments, allowing you to
collect money later, on a schedule, or on demand, with settlement occurring over
standard bank clearing times.

Used together, Instant Bank Pay handles the "right now" payment while Direct Debit
handles ongoing payments. The Instant Bank Pay flow can also capture and verify the
customer's bank details and set up a Direct Debit mandate at the same time. This
gives you immediate payment confirmation up front, plus confidence that the bank
details and mandate are valid for future scheduled or recurring collections,
without requiring the customer to complete two separate setup journeys.

:::note[Availability]
Instant Bank Pay is available for Bacs (UK) and SEPA (EU) only.
:::

Enabling Instant Bank Pay presents a fallback option:

- **IBP Fallback Behavior:**
  - **Fallback to mandate-only (recommended):** If a customer cannot complete Instant Bank Pay,
    they can still complete a Direct Debit mandate and process payment via Direct
    Debit.
  - **Fail transaction if IBP unavailable:** If a customer cannot complete Instant
    Bank Pay, they cannot fall back to Direct Debit and the transaction fails.

![Instant Bank Pay fallback option](/_astro/cdn/f39a684330/connect-4.png)