Partners: Onboarding your users

Helping your users get verified

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.

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.

Checking a user’s verification status

You’ve just taken your user through the OAuth flow, getting an access token that 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 that 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:

1<?php 2require 'vendor/autoload.php'; 3 4$client = new \GoCardlessPro\Client([ 5 'access_token' => $currentUser->gocardlessAccessToken, 6 'environment' => \GoCardlessPro\Environment::SANDBOX 7]); 8 9// The Creditors API returns a list of creditors, but any GoCardless account connected 10// to your application will have a single creditor, so you can just look at the first one 11$creditor = $client->creditors()->list()->records[0]; 12 13// We'll see below how to redirect users to the onboarding flow, and how it works 14if ($creditor->verification_status == "action_required") { 15 redirectToOnboardingFlow(); 16}

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.

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.

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.

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

  • Sandbox:

  • Live:

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.

What's Next

Start building your partner integrationLearn how to setup mandates for your merchants