Integration Guide#

Account set up#

Have you given your app a sensible, public-facing name?

• Your users will see this when they grant you access to their GoCardless accounts through the OAuth flow, and it'll appear in our reporting.

Have you verified your account for payouts?

• This is important if you are receiving a revenue share or adding app fees, as we cannot pay those out otherwise.

Have you added contact details to your account?

• Your contact details are displayed to your clients, so make sure they're up to date.

Are you based in the same country as your merchants?

• If you are in the UK, Bacs will be enabled by default. If you are in the Eurozone, SEPA will be enabled by default.
• You may need to contact our API support team to enable the right scheme on your account.

Merchant onboarding#

Are you using OAuth to get access to your users' accounts?

• OAuth allows a merchant to easily and securely give you access to their account so you can use the GoCardless API on their behalf.

Are you passing the initial_view parameter when you create an OAuth link?

• You can specify whether the OAuth flow should default to showing a login screen or a signup screen.

Are you prefilling merchants' email addresses?

• If you already know your merchant's email address, prefill the OAuth flow using the prefill[email] parameter. You can also prefill their given and family names, and their organisation name.

Have you made it clear that merchants will need to verify their accounts before they can receive payouts?

• Before a merchant can receive payouts, they need to go through GoCardless's onboarding and verification process.
• Using the API, you can check your users' verification state and send them to the onboarding flow if required.
• GoCardless will also send your users email notifications reminding them to verify their account.

Have you made it easy to configure the merchant's account once they've connected? For example, can they configure:

• When payments should be collected?
• How mandates are set up?
• Any reconciliation settings?

If you are charging app fees, is it clear to merchants how much?

Mandate configuration#

Is it easy for merchants to request customers to set up mandates?

• Can merchants send requests to multiple customers in batch?

Can the merchant clearly see which customers have set up a mandate?

• Are you listening to our webhook events and actions?

Can the merchant send reminders to customers to set up mandates?

• A customer might miss the notification to create a mandate — it's good practice to allow sending a reminder after some time has passed.
• Can you automate reminders?

What happens if the mandate fails to be set up?

• Do you inform your user? Do you re-open the invoice?
• Do you help your user understand what went wrong? (more details)

What happens if the mandate is cancelled?

• Do you tell your user?
• Do you provide a way to reinstate the mandate?
• Do you help your user understand what went wrong? (more details)

What happens if the mandate expires?

• Do you tell your user?
• Can you reinstate the mandate?

Can an existing GoCardless merchant import their mandates and match them to customers?

• If yes, do you check whether merchants have subscriptions or plans set up? These may need to be cancelled — contact our API support team for help.
• Find out how to list all or retrieve a single mandate.
• Find out how to list subscriptions.

Can you manage bulk changes (transfers of existing Direct Debits from another provider)?

• Contact our API support team if you want to implement bulk changes.

If you offer multiple payment options, how do you refer to your GoCardless integration?

• Make sure to refer to it as 'pay by Direct Debit' (or the corresponding local scheme name).
• List the GoCardless payment methods, such as 'Pay By Bank' and 'Direct Debit'.

Hosted Payment Pages Optional#

When using the payment pages hosted by GoCardless:

Is it intuitive for end customers to set up mandates?

• Do you include instructions or payment links in emails?
• Do you link to the payment pages from invoices? How does this work for future payments?
• Do you link to the payment pages from your website?

Are you using the description parameter to show a description of what the end customer is signing up for?

• You can set the description when creating a redirect flow.
• Are you allowing your customers to pre-fill the mandate with customer and billing information if available?

Does your redirect URL (after setting up a mandate) look great for an end customer?

• Does it make clear that Direct Debit is set up?
• Does it describe what happens next — for example, when the customer will be charged?

Custom Payment Pages Optional#

Merchants on the Pro/Custom package can request custom payment pages.

If you or your merchants use custom payment pages:

• Have your merchant's payment pages been reviewed by GoCardless?
• Do you make it easy for merchants to create end customers with GoCardless by handling that for them?

If you support setting up mandates by phone:

• Has the script been reviewed and will calls be recorded?
• Are you doing modulus checking using the Bank Details Lookups API?

If your merchant is passing you bank details, are you doing modulus checking?

• Modulus checking is used to do basic validity checking of bank details.
• Use the Bank Details Lookups API.

Mandate transfers#

Are you aware that we only expose the last 2 digits from a bank account when a customer switches bank accounts?

• For security reasons, we only expose the last 2 digits of bank account information via API.
• We'll send a "transferred" webhook when a customer switches bank accounts (more details).
• You can retrieve limited details about an end customer's bank account via the API (more details).
• With the Encrypted Bank Details Access upgrade you can retrieve the full bank details via the API (more details).

Payment collection#

Have you implemented all the available payment methods that GoCardless provides?

• Open banking (more details). [Mandatory]
• Direct Debit (more details). [Mandatory]
• Combining a one-off payment and Direct Debit (more details). [Highly Recommended]

How are you creating payments — individual requests or subscriptions?

• If you're creating one-off payments, be aware that notifications will be sent for each payment (depending on the merchant notification settings).

Can the merchant create a payment as soon as a customer has set up a mandate?

• You don't need to wait until the mandate is active.

Do you allow merchants to schedule payments in advance?

• When creating payments, you can specify an optional charge_date (more details).

Do you enable merchants to collect both one-off and recurring payments? (more details)

For single one-off payments, do you store our mandate ID?

• Storing the mandate ID lets you connect a customer in your database with the mandate on GoCardless, enabling future payments without the customer re-entering bank details.

Are you aware of our maximum £5k limit per transaction?

• Contact our partnerships team for details.

Are you aware of our minimum £1 limit per transaction?

• Contact our partnerships team for details.

Do you allow merchants to retry payments that fail? (more details)

• Payments can be retried up to 3 times.
• You should only retry payments that fail due to insufficient funds.
• Have you factored in Success+ intelligent payment retries? (more details)

What happens when payments fail?

• Do you notify the merchant?
• Do you tell them why it failed?
• Do you reopen the invoice?
• Do you give an option to retry the payment (or automate this)?

Do you use idempotency keys to avoid duplicate payments? (more details)

• You can safely retry creating payments by using idempotency keys.
• Our client libraries allow you to set idempotency keys when creating resources.

Are you charging app fees? (more details)

• Make sure that app fees are never more than 50% of any given payment amount.

Refunds Mandatory#

Do you need refunds enabled for your users?

• This is available for all customers who request this feature.

Are you aware that you can trigger refunds via the API? (more details)

Are you aware that we can only refund against a specific transaction?

• This means a refund shouldn't be used for general payouts like goodwill credits.

Are you making sure to only enable refunds at least 2 days after the customer is charged?

• This avoids refunding a payment that later fails.
• Note that the 7-day safer refund process is enabled by default — customers cannot refund until 7 days have passed (this can be switched off on request).

Do you know that we can still refund a payment even after the mandate has been cancelled?

Payouts and reconciliation#

How are you handling reconciliation when we pay out to your user? (more details)

• Do you mark the corresponding invoice as paid?
• Are fees (included in payouts) shown and posted as expenses?
• Are you marking the payment as paid upon receiving the payment_confirmed event? [Highly Recommended] (more details)
• Are you updating the invoice as paid_out upon receiving the paid_out event? [Recommended for reconciliation] (more details)

Testing in a sandbox environment Highly Recommended#

Have you tested your integration in the sandbox before going live?

• In the sandbox, you can test without real money changing hands. We provide test bank details to make it as simple as possible (more details).
• The sandbox lets you manually trigger cases like a customer cancelling their mandate or a payment failing due to insufficient funds (more details).

Have you connected a separate GoCardless account to your app?

• To mirror a separate merchant connecting to your app, test with a separate account.
• Ensure you aren't using real email addresses in the sandbox, as this will send notifications.

Have you tested payments with your live account?

• After successfully testing in the sandbox, test in live to make sure everything works as expected.

Have you tested the redirect URL flow?

• GoCardless partner apps can have up to twenty redirect URLs, which is useful for testing across development, QA, and other environments.

Error handling#

How does your integration handle API errors?

• Our API reference includes details on errors returned by the API and how to handle them.

Are you aware of our API rate-limiting?

• This might be relevant if you have very high volume merchants. See our API reference for details.

GoCardless brand Recommended#

Are you using the correct GoCardless logo?

• Have a look at the GoCardless branding page for up-to-date logos.

Promoting the integration#

Is it clearly visible how to sign up to GoCardless? For example:

• If you have created a payments tab, link to your GoCardless integration from there.
• Add an alert to your homepage.
• Add relevant in-product prompts, for example when merchants create an invoice or sign a contract.
• Embed or promote setting up payments as part of the new user onboarding experience.
• Include relevant information and links in welcome emails and regular communications.
• Create a landing page with benefits.
• Document your GoCardless integration in the user guide and make it easy to find.
• Add information on your GoCardless integration in the FAQs and help section.