Partners: Integration Checklist

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

• Your users will see this when they give you access to their GoCardless accounts through the OAuth flow, and it’ll also appear on 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 will be?

• If you are in the UK then we’ll enable Bacs by default for you. If you are in the Eurozone then your account will be enabled for SEPA by default.

• You may need to contact our API support team to enable the right scheme on your account.

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?

• When creating an authorisation link, you can specify whether the OAuth flow should default to showing a login screen or a signup screen allowing your user to create a GoCardless accountAre you prefilling merchants’ email addresses?

• If you already know your merchant's email address, make sure to prefill the OAuth flow accordingly. This can be done by specifying the prefill[email] parameter. You can also prefill their given and family names, and their organisation name (e.g. Acme Widget plc).

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 and provide more details about themselves

• 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 to work well with GoCardless 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 that you are charging app fees, and if so how much?

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

• Can merchants send requests to multiple customers in batch?

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

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

• A customer might miss the notification to create a mandate. Therefore it’s good practice to allow sending a reminder after some time has passed.

What happens if the mandate fails to be set up? For example:

• Do you inform your user? Do you re-open the invoice?

• Do you help your user to understand what has gone wrong? (more details)

What happens if the mandate is cancelled? For example:

• Do you tell your user?

• Do you provide a way to reinstate the mandate?

• Do you help your user to understand what has gone wrong? (more details)

   

What happens if the mandate expires? For example:

• 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 to your users’ customers, how do you refer to your GoCardless integration?

• Make sure to refer to your GoCardless integration as ‘pay by Direct Debit’ (or corresponding local scheme names) as this is the underlying payment method.

• Avoid terms like ‘pay by bank transfer’, ‘pay by GoCardless’ or ‘bank payments’ as these might confuse end customers.

When using the payment pages hosted by GoCardless, have a look at the following items:

Is it intuitive for end customers to set up mandates? For example:

• 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.

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

• Does it make clear that Direct Debit is set up?

• Does it describe what happens next? For example, does it mention when the customer will be charged?

Merchants on the Pro package can have custom payment pages. Have a look at the following points to give them the best experience:

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? (e.g. a merchant collects bank details on their custom payment pages and directly forwards them to you. Your integration uses those details to create customers and mandates via GoCardless.)

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? (more details)

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.

• Are you doing modulus checking using the Bank Details Lookups API? (more details)

   

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).

How are you creating payments? Do you create individual payment 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 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?

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

• Storing the mandate ID allows you to connect a customer in your database with the mandate on GoCardless. This means you can use the same mandate for future payments and ensures that the customer doesn’t need to input their bank details again for further payments.

• You can either use the mandate to automatically take future payments (of which the customer will be notified), or get the customer to approve the payment.

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)

• Payment can be retried up to 3 times

• Do you provide automation to retry payments?

• You should only retry payments that fail due to insufficient funds.

What happens when payments fail? For example:

• 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 being created? (more details)

• You can safely retry creating payments by using idempotency keys.

Are you charging app fees? (more details)

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

Do you need refunds enabled for your users?

• This is only available for users on the GoCardless Pro package - contact our partnerships team for details.

Are you aware that you can trigger refunds via the API for users that have them enabled? (more details)

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

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

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

• This avoids refunding on a payment that later fails.

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

How are you handling reconciliation when we payout to your user? For example: (more details)

• Do you mark the corresponding invoice as paid?

• Are fees (included in payouts) shown and posted as expenses?

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

• In the sandbox, you can test your integration without real money changing hands. We provide test bank details to make it as simple as possible (more details).

• The sandbox allows you to manually trigger certain cases (like a customer cancelling their mandate or a payment failing due to insufficient funds) so you can test how your integration responds (more details).

Have you connected a separate GoCardless account to your app?

• To mirror a separate merchant connecting to your app, we recommend testing your integration 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, you might want to test your integration in live to make sure it works as expected.

Have you tested the redirect URL flow?

• GoCardless partner apps can have up to twenty redirect URLs each, which is useful for testing. Edit your app in the dashboard to add endpoints for your development, QA or other environments.

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. Head to our API reference for further details.

Are you using the correct GoCardless logo?

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

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

• If you have created a payments tab, you could 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