Before your users can

  • collect payments from customers and
  • receive payouts of the payments they’ve collected

they’ll need to verify their account. As part of the verification process, your users will need to:

  • Provide information about their business
  • Upload proof of identity and address
  • Add their bank account details, and prove they own the account

We collect these details through our dedicated onboarding flow in order to comply with anti-money laundering regulations. Once a user has signed up to GoCardless through your app, you should send them straight to the onboarding flow to provide these details.

In this guide, we’ll show you how to set up the GoCardless client library so you can access our API using your users’ access tokens.

Once that’s set up, we’ll show you how to query your users’ verification status and, if required, how to send them to our onboarding flow. We’ll collect the information we need and then send the user back to your application.

Setting up your client library

To make it quick and easy to interact with the GoCardless API, we maintain libraries in Java, Python, Ruby, PHP, JavaScript and .NET to talk to our API in those languages without writing lots of boilerplate code.

Of course, you can still use our API if we don’t have a library in your language by building the HTTP requests yourself - see our API reference to get started.

Let’s install the API library using a package manager (you can also, if you prefer, download the source yourself from the links above):

# We strongly recommend using Composer, but if you'd prefer to
# install the PHP library manually, see the instructions at
# https://github.com/gocardless/gocardless-pro-php#manual-installation
composer require gocardless/gocardless-pro "~1.1"

pip install gocardless_pro

echo "gem 'gocardless_pro'" >> Gemfile
bundle install

# Add the following to <dependencies> in your pom.xml
<dependency>
    <groupId>com.gocardless</groupId>
    <artifactId>gocardless-pro</artifactId>
    <version>4.9.2</version>
</dependency>

# Install our NPM package:
npm install gocardless-nodejs

# Install our Nuget package:
install-package GoCardless
Our API libraries have pro in their names, but don’t worry: if you’re starting a new integration, these are the right libraries for you.

Now we can import the library into our code so that it’s ready to use:

require 'vendor/autoload.php';

import gocardless_pro

# In a Rails app, this will happen automatically
require 'gocardless_pro'

import com.gocardless.GoCardlessClient;
const gocardless = require("gocardless-nodejs");

using GoCardless;

You’re now ready to initialise the client - wherever you’re making an API call on behalf of one of your users, you’ll need to pull their GoCardless access token from your database and instantiate the client object with it:

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    // You'll need to identify the user the current user and fetch their access token
    'access_token' => $currentUser->gocardlessAccessToken,
    // Change me to LIVE when you're ready to go live
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

import gocardless_pro

from myintegration import current_user

client = gocardless_pro.Client(
    # You'll need to identify the user the current user and fetch their access token
    access_token=current_user.gocardless_access_token,
    # Change this to 'live' when you are ready to go live.
    environment='sandbox'
)

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  # You'll need to identify the user the current user and fetch their access token
  access_token: current_user.gocardless_access_token,
  # Remove the following line when you're ready to go live
  environment: :sandbox
)

package com.gcintegration;

import com.gocardless.GoCardlessClient;

GoCardlessClient client = GoCardlessClient.create(
    // You'll need to identify the user the current user and fetch their access token
    user.gocardlessAccessToken,
    // Change me to LIVE when you're ready to go live
    GoCardlessClient.Environment.SANDBOX
);

const constants = require("gocardless-nodejs/constants");

const client = gocardless(
  // We recommend storing your access token in an environment
  // variable for security
  process.env.GoCardlessAccessToken,
  // Change me to constants.Environments.Live when you're ready to go live
  constants.Environments.Sandbox
);

var client = GoCardlessClient.Create(
    // We recommend storing your access token in an
    // configuration setting for security
    ConfigurationManager.AppSettings["GoCardlessAccessToken"],
    // Change me to LIVE when you're ready to go live
    GoCardlessClient.Environment.SANDBOX
);

Checking a user’s verification status

You’ve just taken your user through the OAuth flow, getting an access token which you can use to manage their account. Now, if appropriate, you should send them to the onboarding flow so we can gather more information about them which we need before they can receive payouts.

Most of your users will have signed up for their GoCardless account in the OAuth flow itself, so they’ll need to get verified. However, some may have connected existing GoCardless accounts, in which case they won’t need to be verified again. To decide what to do, you should query your user’s verification status.

Your user’s verification status is exposed in the Creditors API through the verification_status attribute. You can query it like this:

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    'access_token' => $currentUser->gocardlessAccessToken,
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

// The Creditors API returns a list of creditors, but any GoCardless account connected
// to your application will have a single creditor, so you can just look at the first one
$creditor = $client->creditors()->list()->records[0];

// We'll see below how to redirect users to the onboarding flow, and how it works
if ($creditor->verification_status == "action_required") {
    redirectToOnboardingFlow();
}

import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

# The Creditors API returns a list of creditors, but any GoCardless account connected
# to your application will have a single creditor, so you can just look at the first one
creditor = client.creditors.list().records[0];

# We'll see below how to redirect users to the onboarding flow, and how it works
if creditor.verification_status == "action_required":
    redirect_to_onboarding_flow()

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
  environment: :sandbox
)

# The Creditors API returns a list of creditors, but any GoCardless account connected
# to your application will have a single creditor, so you can just look at the first one
creditor = client.creditors.list.records.first

# We'll see below how to redirect users to the onboarding flow, and how it works
redirect_to_onboarding_flow if creditor.verification_status == "action_required"
package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Creditor;

import static com.gocardless.resources.Creditor.VerificationStatus.ACTION_REQUIRED;

GoCardlessClient client = GoCardlessClient
    .newBuilder(CurrentUser.gocardlessAccessToken)
    .withEnvironment(GoCardlessClient.Environment.SANDBOX)
    .build();

// The Creditors API returns a list of creditors, but any GoCardless account connected
// to your application will have a single creditor, so you can just look at the first one
Creditor creditor = client.creditors().list().execute().getItems().get(0);

// We'll see below how to redirect users to the onboarding flow, and how it works
if (creditor.getVerificationStatus() == ACTION_REQUIRED) {
  redirectToOnboardingFlow();
}

const client = gocardless(
  // We recommend storing your access token in an environment
  // variable for security
  process.env.GoCardlessAccessToken,
  // Change me to constants.Environments.Live when you're ready to go live
  constants.Environments.Sandbox
);

const creditors = gocardless.creditors.list({ limit: 1 });

// The Creditors API returns a list of creditors, but any GoCardless account connected
// to your application will have a single creditor, so you can just look at the first one
const creditor = creditors.creditors[0];

if (creditor.verification_status === "action_required") {
  // We'll see below how to redirect users to the onboarding flow, and how it works
  redirectUserToOnboardingFlow();
}

GoCardlessClient client = GoCardlessClient.Create(
    // We recommend storing your access token in an
    // configuration setting for security
    ConfigurationManager.AppSettings["GoCardlessAccessToken"],
    // Change me to LIVE when you're ready to go live
    GoCardlessClient.Environment.SANDBOX
);

var creditorListResponse = await gocardless.Creditors.ListAsync(
    new GoCardless.Services.CreditorListRequest() { Limit = 1 }
);

// The Creditors API returns a list of creditors, but any GoCardless account connected
// to your application will have a single creditor, so you can just look at the first one
GoCardless.Resources.Creditor creditor = creditorListResponse.Creditors[0];

if (creditor.VerificationStatus == CreditorVerificationStatus.ActionRequired)
{
    // We'll see below how to redirect users to the onboarding flow, and how it works
    RedirectUserToOnboardingFlow();
}

A creditor’s verification status can have one of three values:

  • successful: the creditor’s account is fully verified, and they can receive payouts
  • in_review: the creditor has provided all of the information requested, and it is awaiting review by GoCardless before they can receive payouts
  • action_required: the creditor needs to provide further information to verify their account so they can receive payouts, and should visit the onboarding flow

If your user has just connected to your app and they’re in the action_required state, you should send them to the onboarding flow straight away.

It’s worth noting that your users, after being successfully verified, may later require further verification and go back to the in_review or action_required states. For example, if your user changes the bank account where they receive payouts, we’ll need to check that the new bank account belongs to them before they can receive payouts, so they’ll revert to the action_required state.

We’d suggest including appropriate cues in your UI if your users aren’t in the successful state, letting them know that they won’t receive payouts, and directing them to the onboarding flow if they’re in the action_required state.

You probably won't want to poll the Creditors API on every pageload for your user's verification_status. We'd recommend caching this and refreshing it regularly, as well as at times when it makes sense in your user journey (for example when a user returns to your app through the post-onboarding URL).

Sending your user to the onboarding flow

GoCardless provides a dedicated onboarding flow where you can send your users to go through the verification process.

Onboarding flow

Once they’ve finished providing the information required, the UI will link your user directly back to your product, using the “Post-onboarding URL” specified on your app.

Creating a GoCardless OAuth app

To start the onboarding and verification process, send your user to:

When your user lands back in your product, it’s likely that their verification status will not yet be successful - some of the information provided by users requires review by GoCardless, so it may be a little while before they move to the successful state, or in some cases further information will be requested, meaning they’ll move back to action_required.

Setting up Direct Debit mandates →