# Integration Guide

Source: https://docs.gocardless.com/docs/partner-integrations/integration-guide

# Integration Guide

## Best practices

We want to help you build a great integration that delivers real value to your users. Work through this checklist before going live to make sure you've covered everything.

  
### Setup

### 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](mailto:api@gocardless.com) to enable the right scheme on your account.

    ### Merchant onboarding

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

    - [OAuth](/docs/partner-integrations/connect-your-merchants) 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?**

  
### Mandates

### 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)](/docs/api-reference/events/mandates)

    **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)](/docs/api-reference/events/mandates)

    **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](mailto:api@gocardless.com) for help.
    - Find out how to [list all](/docs/api-reference/mandate#list-mandates) or [retrieve a single mandate](/docs/api-reference/mandate#get-a-single-mandate).
    - Find out how to [list subscriptions](/docs/api-reference/subscription#list-subscriptions).

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

    - [Contact our API support team](mailto:api@gocardless.com) 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 OptionalWhen using the [payment pages hosted by GoCardless](/docs/collect-payments/setting-up-mandates):

    **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](/docs/api-reference/redirect-flow#create-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 OptionalMerchants 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](/docs/api-reference/bank-details-lookup)?

    **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](/docs/api-reference/bank-details-lookup).

    ### 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)](/docs/api-reference/events/mandates).
    - You can retrieve limited details about an end customer's bank account via the API [(more details)](/docs/api-reference/customer-bank-account).
    - With the Encrypted Bank Details Access upgrade you can retrieve the full bank details via the API [(more details)](/docs/gc-embed/bank-details-access).

  
### Payments

### Payment collection

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

    - Open banking [(more details)](/docs/collect-payments/one-off-payments/pay-by-bank). **[Mandatory]**
    - Direct Debit [(more details)](/docs/collect-payments/setting-up-mandates). **[Mandatory]**
    - Combining a one-off payment and Direct Debit [(more details)](/docs/collect-payments/recurring-payments/instant-first-payment-with-mandate). **[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)](/docs/api-reference/payment#create-a-payment).

    **Do you enable merchants to collect both one-off and recurring payments?** [(more details)](/docs/collect-payments/one-off-payments/pay-by-bank)

    **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](https://gocardless.com/contact-sales/?s=partners) for details.

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

    - [Contact our partnerships team](https://gocardless.com/contact-sales/?s=partners) for details.

    **Do you allow merchants to retry payments that fail?** [(more details)](/docs/api-reference/payment#retry-a-payment)

    - 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)](/docs/optimise/reduced-failed-payments-with-success-plus)

    **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)](/docs/api-reference/limits#idempotency-keys)

    - 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)](/docs/partner-integrations/connect-your-merchants)

    - 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)](/docs/api-reference/refund#create-a-refund)

    **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)](/docs/collect-payments/managing-payments/reconciling-payouts)

    - 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)](/docs/api-reference/events/payments)
    - Are you updating the invoice as paid_out upon receiving the `paid_out` event? **[Recommended for reconciliation]** [(more details)](/docs/api-reference/events/payments)

  
### Going live

### Testing in a sandbox environment Highly Recommended**Have you tested your integration in [the sandbox](https://manage-sandbox.gocardless.com/signup) 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)](/docs/developer-resources/test-bank-details).
    - The sandbox lets you manually trigger cases like a customer cancelling their mandate or a payment failing due to insufficient funds [(more details)](/docs/developer-resources/scenario-simulators).

    **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](/docs/api-reference/responses-and-errors) 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](/docs/api-reference/limits#rate-limiting) for details.

    ### GoCardless brand Recommended**Are you using the correct GoCardless logo?**

    - Have a look at the [GoCardless branding page](https://brand.gocardless.com/) 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.

## What's Next?

  
#### [Go-live checklist](/docs/partner-integrations/go-live-checklist)

Complete the steps required to move your integration from sandbox to production.

  
#### [UX guides & resources](/docs/partner-integrations/ux-guides-and-resources)

Follow UX best practices for surfacing GoCardless in your product.