Billing Requests: Verified Mandates

Collect Verified Mandates

Note: Verified Mandates feature is only available to approved integrators with the Verified Mandates upgrade. Verified Mandates upgrade is enabled by default for merchants with Standard or Plus package. If you're interested in trying it out - please contact support.

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.

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 fraudulent 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	No
🇸🇪 Autogiro	`autogiro`	Yes	Yes
🇬🇧 Bacs	`bacs`	Yes	No
🇦🇺 BECS	`becs`	No	-
🇳🇿 BECS NZ	`becs_nz`	No	-
🇩🇰 Betalingsservice	`betalingsservice`	No	-
🇨🇦 PAD	`pad`	No	-
🇪🇺 SEPA Core	`sepa_core`	Germany 🇩🇪, France 🇫🇷	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 Protect+ to decide if a payer should be verified
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 use the recommended verification preference. It uses Protect+ to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended behaves like minimum.

If you never wish to take advantage of Protect+ and Verified Mandates as they are released in new schemes, please use the minimum verification preference.

Let us know you’re interested

Whilst we continually improve our verification flows, not all banks are available or supported and some flows may fail due to device-specific issues.

We recommend only setting when_available or always when you are happy with some potential impact on conversion in favour of drastically reduced risk. To help optimise your flows we advise using the recommended setting. This can be combined with our anti-fraud product Protect+ for increased protection and verification while maintaining good conversion rates.

How-to

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 a bacs mandate, as that scheme supports verification.

Let's begin!

Goal - Create a Direct Debit mandate using Billing Request

Engineering complexity - Easy

Time taken - 15 minutes

Use the Create a Billing Request endpoint:

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequests()->create([
  "params" => [
    "mandate_request" => [
      "scheme" => "bacs",
      "verify" => "when_available"
    ]
  ]
]);

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

The response will look like this:

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

As Bacs 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.

Goal - Create a Billing Request Flow that can be used for your customer to authorise payments

Engineering complexity - Easy

Time taken - 15 minutes

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:

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequestFlows()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "exit_uri" => "https://my-company.com/exit",
    "links" => [
      "billing_request" => "BRQ000010NMDMH2"
    ]
  ]
]);

UX Preview

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"
    }
  }
}

What the customer will see

When the customer opens the authorisation link, they'll see a form that goes through the following steps. The example is shown for the 🇬🇧 Bacs scheme.

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.

Examples in other schemes

For the Autogiro scheme, it is a requirement to put all the payers setting up the Direct Debit Mandate through BankId verification. This means you will need the Verified Mandates upgrade enabled in order to have mandates set up in the Autogiro scheme.