Taking Direct Debit payments using Billing Requests and Custom Payment Pages

What is a billing request?

For the purposes of this tutorial, a Billing Request is a wrapper around all of the GoCardless APIs required to take a payment from a customer. This allows you, the integrator, to define desired outcomes upfront (for example, "I want to take a payment from X") and guides you through the process to achieve them.

What is the aim of this tutorial?

This tutorial aims to familiarise beginners with using Billing Requests to collect Direct Debit payments using Custom Payment Pages. It will not cover Instant Bank payments (IBP) or VerifiedMandates (VM).

Getting started

For this tutorial, you will need:

An API token
The GoCardless client library of your choice configured in your language of choice
A Creditor to collect payments against

Creating a Billing Request

We can start by creating a Billing Request. This will allow us to request a Mandate to take a payment against that is linked to a Creditor.

POST https://api.gocardless.com/billing_requests HTTP/1.1
Content-Type: application/json
{
  "billing_requests": {
    "mandate_request": {
      "scheme": "bacs"
    },
    "links": {
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 Created
Location: /billing_requests/BRQ123
Content-Type: application/json
{
    "billing_requests": {
        "id": "BRQ123",
        "created_at": "2023-03-22T15:20:08.397Z",
        "status": "pending",
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "links": {}
        },
    ...
}

For the purposes of this tutorial, we only need to keep track of the ID of the Billing Request: BRQ123

We request the desired scheme, in this instance, we are going to use bacs for a GBP mandate. If you want to collect in EUR, use sepa_core. We link the Billing Request to the creditor we wish to pay out to, CR123.

In the next steps, we complete the required Billing Request actions to fulfil our request. The actions returned from the API describe steps that must be taken for a Billing Request to be fulfilled. They can change depending on the type of payment being taken or set up (e.g a Direct Debit or Instant Bank payment). We don’t need to worry about them too much in this tutorial - but it’s good to be aware of them! You can read more about them here if you’re interested.

Collect customer details

Next, we need to collect the details of our customer

POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_customer_details HTTP/1.1
Content-Type: application/json
{
  "data": {
    "customer": {
      "email": "alice@example.com",
      "given_name": "Alice",
      "family_name": "Smith"
    },
    "customer_billing_detail": {
      "address_line1": "1 Somewhere Lane",
      "city": "London",
      "postal_code": "E5 8EE",
      "country_code": "GB"
    }
  }
}

HTTP/1.1 200
Content-Type: application/json
{
  "billing_requests": {
    "id": "BRQ123",
    ...
    "links": {
      "customer": "CU123",
      "customer_billing_detail": "CBD123"
    },
    ...
  },
  "resources": {
    "customer": {
      "id": "CU123",
      "created_at": "2021-03-22T12:20:04.238Z",
      "email": "alice@example.com",
      "given_name": "Alice",
      "family_name": "Smith",
      ...
    },
    "customer_billing_detail": {
      "id": "CBD123",
      "created_at": "2021-03-22T12:20:04.374Z",
      "address_line1": "1 Somewhere Lane",
      ...
    }
  }
}

Note we now have a link to a Customer and Customer Billing Detail

Collect bank account details

Now we need to collect the customer bank account details to be able to create a Mandate against the customer.

POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_bank_account HTTP/1.1
Content-Type: application/json
{
  "data": {
    "account_number": "55779911",
    "branch_code": "200000",
    "account_holder_name": "Alice Smith",
    "country_code": "GB"
  }
}

HTTP/1.1 200
Content-Type: application/json
{
  "billing_requests": {
    "id": "BRQ123",
    ...
    "links": {
      "customer": "CU123",
      "customer_billing_detail": "CBD123"
    },
    ...
  },
  "resources": {
    "customer": {
      "id": "CU123",
      "created_at": "2021-03-22T12:20:04.238Z",
      "email": "alice@example.com",
      "given_name": "Alice",
      "family_name": "Smith",
      ...
    },
    "customer_billing_detail": {
      "id": "CBD123",
      "created_at": "2021-03-22T12:20:04.374Z",
      "address_line1": "1 Somewhere Lane",
      ...
    },
    "customer_bank_account": {
      "id": "BA123",
      "created_at": "2021-03-22T12:20:04.374Z",
      "account_holder_name": "Alice Smith",
      "account_number_ending": "11",
      "country_code": "GB",
      "currency": "GBP",
      "bank_name": "BARCLAYS BANK PLC",
      "enabled": true,
      "links": {
        "customer": "CU123"
      }
    }
  }
}

Confirm Payer details

This is needed when you have a Mandate Request. As a scheme compliance rule, we are required to allow the payer to crosscheck the details entered by them and confirm them.

For a live integration, you would want to show a summary of the payer details (the information we took in the previous two steps) and give the option to cancel. For the purposes of this tutorial, we can just call the confirm endpoint.

POST https://api.gocardless.com/billing_requests/BRQ123/actions/confirm_payer_details HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
  "billing_requests": {
    "id": "BRQ123",
    "mandate_request": {
      "currency": "GBP",
      "scheme": "bacs",
      "links": {
        "mandate": "MD123"
      }
    },
    "actions": [
      ...
      {
        "type": "confirm_payer_details",
        "required": true,
        "requires_actions": [
          "collect_customer_details",
          "collect_bank_account"
        ],
        "status": "completed"
      }
      ...
    ]
  }
}

We want to keep track of our Mandate ID for the step where we take a payment.

Fulfil

This step ‘executes’ the Billing Request, using the contents of our request to create a Mandate. This will create a Mandate within GoCardless to take payments against. The fulfil action is the step where the collected Information will be submitted to our partner bank(s).

It can be batched with the confirm payer details call above. It is a separate step (and API call) as we may sometimes want to combine different types of payment (e.g Open banking) with the creation of a Mandate.

POST https://api.gocardless.com/billing_requests/BRQ123/actions/fulfil HTTP/1.1

HTTP/1.1 200
Content-Type: application/json
{
  "billing_requests": {
    "id": "BRQ123",
    "status": "fulfilled",
    ...
  },
  ...
}

Taking a payment

We can now use the GoCardless Payments API to take a payment against our newly created Mandate!

POST https://api.gocardless.com/payments HTTP/1.1
Content-Type: application/json
{
  "payments": {
    "amount": 1200,
    "currency": "GBP",
    "reference": "Wine Box",
    "metadata": {
      "order_dispatch_date": "2023-03-29"
    },
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 201 Created
Location: /payments/PM123
Content-Type: application/json
{
  "payments": {
    "id": "PM123",
    "created_at": "2023-03-22T17:01:06.000Z",
    "charge_date": "2023-03-24",
    "amount": 1200,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2023-03-29"
    },
    ...
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    }
  }
}

Note that we charge the amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

We can see the date that the payment will be taken by looking at the charge_date in the response.

What's next?

Handling webhooks

Need help?

Connect as a partner