# UX Guides & Resources

Source: https://docs.gocardless.com/docs/partner-integrations/ux-guides-and-resources

# User Experience Guide

This guide is intended to help you build the best experience for your users. We've imagined a simple invoicing application (called 'Acme') to help illustrate the recommendations. The sections below serve as a checklist for things you should consider when integrating with GoCardless.

  
#### [1. General recommendations](#general-recommendations)

High-level principles that apply throughout the integration.

  
#### [2. Discovering GoCardless](#discovering-gocardless-while-using-your-product)

Where and how to surface GoCardless within your product.

  
#### [3. Setting up the integration](#setting-up-the-gocardless-integration)

Making the OAuth connection flow seamless for merchants.

  
#### [4. Verifying in GoCardless](#verifying-in-gocardless)

Prompting merchants to verify before they can receive payouts.

  
#### [5. Requesting a Direct Debit mandate](#requesting-a-customer-to-set-up-a-direct-debit)

How to ask customers to set up a mandate across different touchpoints.

  
#### [6. Collecting a payment](#collecting-a-payment)

Surfacing payment collection at the right moment in your UI.

  
#### [7. Automating payments](#automating-payments-and-direct-debit-requests)

Encouraging merchants to automate to improve cash flow.

  
#### [8. Displaying error states](#clearly-displaying-error-states)

Helping merchants act when mandates fail or payments are rejected.

## General recommendations

Before we look at the different steps in the user journey, here are some high-level principles that apply throughout:

  
#### Keep key actions in your product

Frequent actions like taking payments and managing mandates should live in your interface. Less
    frequent tasks like settings and help can live in GoCardless.

  
#### Provide help resources

Give users a way to get in touch and link to relevant GoCardless resources at each step of the
    journey — especially during onboarding.

  
#### Use clear, concise language

Let users know where they are and what is happening at every step of the flow.

## Discovering GoCardless while using your product

The first thing to consider is how to let your users know that they can use a GoCardless integration with your product. When you do that, provide a clear way for them to add the integration, explain the value of GoCardless in a clear and concise way, and focus on our main benefits:

- GoCardless is made for recurring payments.
- GoCardless allows you to collect invoice payments and subscriptions.
- GoCardless allows you to split payments into multiple instalments and collect payments in different currencies (if you support these features).

Display this information at steps of the journey where it will be relevant to them. These steps tend to be the following for the majority of our partners:

### During onboarding

Encourage them to add a payment method while they're getting started with your product:

![02-onboarding-add-method](/images/docs/partner-integrations/ux-guides-and-resources/02-onboarding-add-method.jpeg)

### While adding a new customer

Encourage them to set up a payment method when they are adding a new customer:

![03-new-customer-add-method](/images/docs/partner-integrations/ux-guides-and-resources/03-new-customer-add-method.jpeg)

### When sending an invoice

Bring GoCardless to their attention when they are thinking about invoicing their customer.

![04-new-invoice-add-method](/images/docs/partner-integrations/ux-guides-and-resources/04-new-invoice-add-method.jpeg)

### On your settings page

If you offer a way to add a payment method from your settings page, make them aware that they can also add GoCardless now.

![05-payment-settings-add-method](/images/docs/partner-integrations/ux-guides-and-resources/05-payment-settings-add-method.jpeg)

## Setting up the GoCardless integration

Make the setup process as seamless as possible — connecting your product and GoCardless should require as few steps as possible. At this point, you should **explain clearly what is happening and reassure your users**.

![06-connect](/images/docs/partner-integrations/ux-guides-and-resources/06-connect.jpeg)

## Verifying in GoCardless

Once the integration is set up, your user might need to verify their GoCardless account. You can check whether this is [required through the API](/docs/partner-integrations/getting-your-users-verified), and direct the user to our onboarding flow if needed. Ask them to verify in a way that is noticeable and feels important — **they won't receive payouts if they don't**.

![07-dashboard-verify-reminder](/images/docs/partner-integrations/ux-guides-and-resources/07-dashboard-verify-reminder.jpeg)

## Requesting a customer to set up a Direct Debit

### During customer onboarding

The next step for your user is to request a customer to complete a Direct Debit mandate so they can take payments from them. **You should do this when they are onboarding a new customer**, as that is the step where the user and their customer are thinking about payment settings.

![08-new-customer-method-added](/images/docs/partner-integrations/ux-guides-and-resources/08-new-customer-method-added.jpeg)

### Bulk requests

Allow your users to **make multiple mandate requests in bulk** to save time when onboarding multiple customers at once.

![09-customers-bulk-actions](/images/docs/partner-integrations/ux-guides-and-resources/09-customers-bulk-actions.jpeg)

### Shareable mandate links

You can also **provide a mandate setup link in your product that your merchants can copy** and use wherever they like, for example in emails or on their website. See [setting up Direct Debit mandates](/docs/partner-integrations/setting-up-mandates) for how to implement this.

![17-generic-link](/images/docs/partner-integrations/ux-guides-and-resources/17-generic-link.jpeg)

You can also let your users know about the ability to **import existing mandates** they may have already set up using the GoCardless dashboard or via another integration.

![18-mandate-import](/images/docs/partner-integrations/ux-guides-and-resources/18-mandate-import.jpeg)

### Email notifications

Your users will want to know what their customers will see and have control over what is sent to them. If your integration sends emails to customers requesting a mandate, offer a **preview of the email and the option to edit the copy**. See [handling customer notifications](/docs/tutorials/handling-customer-notifications) for how to implement this.

![10-email-template](/images/docs/partner-integrations/ux-guides-and-resources/10-email-template.jpeg)

### On invoices

**Invoices and subscription pages** are another natural touchpoint where merchants think about payment settings. Encourage them to request a mandate here too.

![11-new-invoice-dd-not-setup](/images/docs/partner-integrations/ux-guides-and-resources/11-new-invoice-dd-not-setup.jpeg)

If you allow mandate requests when sending an invoice, surface it as a **"Pay with Direct Debit"** button on the invoice itself.

![12-invoice-preview-dd-not-setup](/images/docs/partner-integrations/ux-guides-and-resources/12-invoice-preview-dd-not-setup.jpeg)

### Confirmation screen

Consider designing a confirmation screen for customers to land on after completing a mandate. Show a **clear message confirming the Direct Debit is set up and what happens next**.

![19-dd-confirmation](/images/docs/partner-integrations/ux-guides-and-resources/19-dd-confirmation.jpeg)

### Displaying mandate status

Your users will want to see which customers have a Direct Debit set up and which ones they need to follow up with. Display the [Direct Debit status](/docs/api-reference/mandate) clearly on both the customer list and the individual customer page.

![20-customer-status](/images/docs/partner-integrations/ux-guides-and-resources/20-customer-status.jpeg)

![13-customer-page](/images/docs/partner-integrations/ux-guides-and-resources/13-customer-page.jpeg)

## Collecting a payment

Once a Direct Debit mandate has been set up, your user can collect payments. The most common moment is when creating an invoice or subscription, so surface that option there. **Explain clearly what options are available and how the payment process works**.

![14-new-invoice-dd-setup](/images/docs/partner-integrations/ux-guides-and-resources/14-new-invoice-dd-setup.jpeg)

Your users need to see the [status of every payment](/docs/api-reference/payment). Display it clearly on an overview page like an invoices list as well as the individual invoice or subscription page.

![15-invoices](/images/docs/partner-integrations/ux-guides-and-resources/15-invoices.jpeg)

![16-new-invoice-paid](/images/docs/partner-integrations/ux-guides-and-resources/16-new-invoice-paid.jpeg)

If payments aren't collected automatically, **allow users to choose when to collect — as soon as possible or at a later date**. Make sure your implementation creates the payment early enough to hit the date the merchant needs.

![21-manual-collection-scheduled](/images/docs/partner-integrations/ux-guides-and-resources/21-manual-collection-scheduled.jpeg)

## Automating payments and Direct Debit requests

Automation helps your users improve cash flow and reduces admin time. **Once your user has collected their first payment, encourage them to automate collections and mandate requests.** Lead with cash flow when prompting automation on invoices or subscriptions.

![22-new-invoice-dd-setup-callout](/images/docs/partner-integrations/ux-guides-and-resources/22-new-invoice-dd-setup-callout.jpeg)

Lead with reduced admin when prompting automation of Direct Debit requests, and surface it at the right moment — for example, when adding a new customer.

![23-new-customer-method-added-callout](/images/docs/partner-integrations/ux-guides-and-resources/23-new-customer-method-added-callout.jpeg)

If you support [automatically retrying payments](/docs/optimise/reduced-failed-payments-with-success-plus), draw your users' attention to it once it's relevant to them.

![26-retry-automation](/images/docs/partner-integrations/ux-guides-and-resources/26-retry-automation.jpeg)

## Clearly displaying error states

When things go wrong, **alert your users and help them understand the best action to take**.

If a mandate has failed, been cancelled, or expired, notify your user and encourage them to contact their customer.

![24-customers-failed](/images/docs/partner-integrations/ux-guides-and-resources/24-customers-failed.jpeg)

For payment failures:

- Highlight failed payments and clearly display the reason for the failure.
- Ensure invoices are not marked as paid, and make it as easy as possible to retry.
- Provide a way to resend a mandate request when a payment has failed due to a mandate issue.

![25-invoices-failed](/images/docs/partner-integrations/ux-guides-and-resources/25-invoices-failed.jpeg)

## What's Next?

  
#### [Integration guide](/docs/partner-integrations/integration-guide)

Work through the best-practices checklist to ensure a production-ready integration.

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

Complete the self-assessment review before going live.