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 collect payments from customers and receive payouts of the payments they’ve collected.
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 collect payments from customers and receive payouts of the payments they’ve collected.in_review: the creditor has provided all of the information requested, and it is awaiting review by GoCardless before they can collect payments from customers and receive payouts of the payments they’ve collectedaction_required: the creditor needs to provide further information to verify their account so they can collect payments from customers and receive payouts of the payments they’ve collected, 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 can't collect payments from customers and can't receive payouts of the payments they’ve collected, 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:
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