This guide shows how to take a combined instant first payment and direct debit mandate in a single Billing Request, sending the customer through a GoCardless hosted Billing Request Flow to fulfil the request.

Note: Currently only the BACS scheme is supported for Direct Debit mandates. Other schemes are coming soon.

Create a Billing Request

To take both an instant first payment and to setup a mandate you must include both the payment_request and mandate_request fields when creating your Billing Request.

Note: You will be allowed to create a Billing Request only if the `mandate_request` and the `payment_request` have the same currency.

Mandates are created against a particular payment scheme, however an integrator will normally only care about the currency they are using to create payments. 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 and take the first payment against an existing customer, just specify the customer ID in links.customer

Use the Create a Billing Request endpoint:

POST /billing_requests
{
  "billing_requests": {
    "payment_request": {
       "currency": "GBP",
       "amount": "500",
       "description": "£5 Instant first payment"
    },
    "mandate_request": {
       "currency": "GBP"
    }
  }
}

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

It will look like this:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "mandate_request": {
       "currency": "GBP",
       "scheme": "bacs",
    },
    "payment_request": {
      "currency": "GBP",
      "amount": "500",
      "description": "£5 Instant first payment",
      "scheme": "faster_payments"
    },
    "links": {
      "customer": "CU00016VR36GVW",
      "customer_billing_detail": "CBD000010M15PAC",
      "payment_request": "PRQ123",
      "mandate_request": "MRQ123"
    }
  }
}

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 GoCardless 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/billing/static/flow?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 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. Collect bank details

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

Collect required bank account in order for GC to take a payment.

Collect bank details

3. Preview payment details

Preview the payment and bank, before authorising anything.

Preview payment details

4. Go to their bank

Go to their bank to complete the authorisation. Customers can use the QR code to jump directly into their mobile banking app (this is the best UX in most cases) or opt to continue on desktop.

Go-to their bank

5. Confirmation

View confirmation that the direct debit has been set up and the payment has been successful once the bank authorisation is complete.

Confirmation

Done!

The first instant payment with Direct debit mandate set up has now been complete, and the Billing Request is fulfilled. Because this is an instant first payment, the funds are confirmed within minutes of the request going through, and leave the customer’s bank account immediately. You can also create future payments against the Direct Debit mandate created.