This guide shows how to take an instant bank payment with Billing Requests, sending the customer through a GoCardless hosted Billing Request Flow to fulfil the request.

Create a Billing Request

Create a Billing Request that specifies the payment_request you want to take from your customer.

Our example will take a payment from an existing customer, by specifying the customer ID under links.customer. Leave this blank to setup a totally new customer.

Use the Create a Billing Request endpoint:

POST /billing_requests
{
  "billing_requests": {
    "payment_request": {
       "currency": "GBP",
       "amount": "500",
       "description": "£5 Top Up"
    },
    "links": {
      "customer": "CU00016VR36GVW"
    }
  }
}

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": null,
    "payment_request": {
      "currency": "GBP",
      "amount": "500",
      "description": "£5 Top Up",
      "scheme": "faster_payments"
    },
    "links": {
      "customer": "CU00016VR36GVW",
      "customer_billing_detail": "CBD000010M15PAC"
    }
  }
}

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/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 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 payment has been successful once the bank authorisation is complete.

Confirmation

Done!

The payment has now been complete, and the Billing Request is fulfilled. Because this is an instant bank payment, the funds are confirmed within minutes of the request going through, and leave the customer’s bank account immediately.