This guide shows how to create a Direct Debit mandate with Billing Requests, sending the customer through a GoCardless hosted Billing Request Flow to fulfil the request.

Note: Currently creating Direct Debit mandate for AUTOGIRO scheme is not supported

Create a Billing Request

Create a Billing Request that specifies the type of mandate you wish to create via the mandate_request field.

Mandates are created against a payment scheme. Most integrators will only care about the currency that the mandate enables charging. We recommend specifying a currency and omitting the scheme, allowing GoCardless to pick the best scheme for that currency.

Most integrators will use Billing Requests to create a mandate alongside a new customer, so we’ll use that as our example. If you want to create a mandate against an existing customer, just specify the customer ID in links.customer.

Use the Create a Billing Request endpoint:

POST /billing_requests
{
  "billing_requests": {
    "mandate_request": {
      "currency": "GBP"
    }
  }
}

You’ll receive a full Billing Request, including things like actions and resources.

It will look like this, some detail omitted:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "payment_request": null,
    "mandate_request": {
      "currency": "GBP",
      "scheme": "bacs"
    },
    "links": {
      "customer": "CU00016WDAM7BS",
      "customer_billing_detail": "CBD000010PDF4WD",
      "mandate_request": "MRQ123"
    },
    "actions": [
      {
        "type": "collect_customer_details",
        "status": "pending",
      },
      {
        "type": "collect_bank_account",
        "status": "pending"
      }
    ]
  }
}

The Billing Request is currently pending, meaning we need to complete the outstanding actions before it can be fulfilled. We can use Billing Request Flows to generate a checkout flow that guides the payer through these actions.

Integrators building custom payment pages should read the Billing Request actions guide to understand what actions are available, and how to complete them.

If you complete actions yourself, you can resume this guide to have Billing Request Flows complete whatever remain.

Read on to use the hosted flow!

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/flow/static/billing_request?id=<br_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 accesses the link and 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 satisfy scheme compliance.

2. Collect bank details

Note: this screen is skipped if the details already exist or the bank account is locked.

Collect bank account that will be used to setup the Direct Debit.

Collect bank details

3. Preview mandate details

The customer is shown a confirmation of the details they are using to complete the setup along with a preview of the mandate pdf (accessible through the link) from which they can edit or correct any mistakes.

Preview mandate details

4. Confirmation

A final screen confirms that the setup of the mandate was successful and that the payer has completed the flow. If a redirect url was specified they will be redirected here.

Confirmation

Done!

The mandate has now been created, and is ready to create payments against. The Billing Request is fulfilled, and cannot be modified.