Please note that by updating your API integration and using the Verified Mandates feature you agree to be bound by the Product Specific Terms, which can be found here, and which have been updated to set out the terms applicable to your use of the feature.

The product described here is in early-access. This means the verification mechanisms are excluded from our normal SLA, may change as we develop them, and are only available on request. Please get in touch (api@gocardless.com) if you're interested in trying it out.

This guide shows how to create a Verified Mandate by creating a Billing Request which opts-into customer bank account verification, and sending the customer through a GoCardless hosted Billing Request Flow to complete the verification.

By verifying the customer has access to the bank account the Direct Debit mandate will be created against, you can protect yourself against fradulent payers.

Before we begin: Availability and Preference

Verified Mandates use different mechanisms depending on the scheme of the mandate in the Billing Request.

Here is a full list of supported Bank Debit schemes, whether a verification mechanism is available, and whether scheme compliance requires a customer to perform the verification.

Scheme API Available Required by Scheme
ACH ach Yes (Plaid) No
Autogiro autogiro Yes (BankID) Yes
Bacs bacs No -
BECS becs No -
BECS NZ becs_nz No -
Betalingsservice betalingsservice No -
PAD pad No -
SEPA Core sepa_core No -

To request verification for your mandate, you must set the verify attribute of the mandate_request to a level that matches your preference.

Verification preference can be one of:

  • minimum: only verify if absolutely required, such as when part of scheme rules
  • recommended: in addition to minimum, use the GoCardless risk engine to decide an appropriate level of verification
  • when_available: if verification mechanisms are available, use them
  • always: as `when_available`, but fail to create the Billing Request if a mechanism isn't available

By default, all Billing Requests will use recommended.

In this how-to, we’ll opt for when_available to ensure we apply the verification if the scheme supports it. And as per our Availability, we’ll be creating an ach mandate, as that scheme supports Plaid verification.

Let’s begin!

Create a Billing Request

Use the Create a Billing Request endpoint:

POST /billing_requests
{
  "billing_requests": {
    "mandate_request": {
      "scheme": "ach",
      "verify": "when_available"
    }
  }
}

This will create a new Billing Request, asking for an ACH mandate and requesting a when_available verification preference.

The response will look like this:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "mandate_request": {
      "currency": "USD",
      "scheme": "ach",
      "verify": "when_available"
    },
    "actions": [
      {
        "type": "bank_authorisation",
        "required": true,
        "status": "pending"
      }
    ]
  }
}

As ACH supports verification, you’ll see we have a bank_authorisation action in the Billing Request response. Note the action is required, which means we cannot fulfil this request without first completing the bank authorisation.

We can use Billing Request Flows to generate a checkout flow that guides the payer through these actions, including the verification via bank authorisation.

Create a Billing Request Flow

Billing Request Flows can be created against Billing Requests, and provide an entry into a hosted GoCardless flow that completes whatever actions remain against the request.

Create a Billing Request Flow to retrieve a link that can be provided to your customer to complete the request:

POST /billing_request_flows
{
  "billing_request_flows": {
    "redirect_uri": "https://my-company.com/completed",
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

This returns a new flow, which has an authorisation_url you should send to your customer:

{
  "billing_request_flows": {
    "authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=<brf-id>",
    "lock_customer_details": false,
    "lock_bank_account": false,
    "auto_fulfil": true,
    "created_at": "2021-03-30T16:23:10.679Z",
    "expires_at": "2021-04-06T16:23:10.679Z",
    "redirect_uri": "https://my-company.com/completed",
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

Customer completes the flow

When the customer opens the authorisation link, they’ll see a form that goes through the following steps:

1. Collect customer details

Note: this screen is skipped if the details already exist, or the customer details have been locked.

Collect customer details in order to complete the billing request.

Collect customer details

2. Start verification

Customers can start the verification process by clicking continue.

This is an example of a possible verification mechanism, but different schemes will have different flows, and we reserve the right to change the mechanism to better suit scheme or business needs.

Start verification

3. Complete verification

Using Plaid as an example verification mechanism, the customer should login to their bank account and authorise GoCardless to read their details.

Plaid continue

Use the username user_good and password pass_good for testing Plaid in the GoCardless sandbox environment.

Plaid login

4. Confirm details

Preview the details and Direct Debit guarantee (changes per scheme) before agreeing to setup the mandate.

Confirm details

5. Success

Everything has been setup, and we show a success screen before redirecting back to the Billing Request Flow redirect_uri.

Success

Done!

The Direct Debit mandate has now been created, and the Billing Request is fulfilled. Note that the mandate will have a verified_at timestamp set to the last successful verification, which can be used to identify which mandates have been verified.

You can use the Create Payments endpoint to create new payments against the mandate, or use the mandate in other resources such as when Creating a Subscription.