Prefilling customer details

If you already hold information about your customer (the payer), you can provide this information before sending your customer through a Billing Request Flow. As a result of prefilling customer data, the customer will need to perform fewer steps to complete their payment flow. This leads to a more seamless experience with less friction for the customer and will result in higher conversion.

There are three ways that prefilling can be done.

Create a customer record via the Collect Customer Details endpoint (Note: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with custom payment pages upgrade).
- Doing so will mean that the customer won’t have to complete the customer details page in the Billing Request Flow. They will start the journey further along.
Use an existing customer record with the Billing Request API.
- Again the customer will not have to complete the customer details page. This is possible because the customer’s details are already available.
Provide customer data as values into the Billing Request Flows API.
- The customer will have their details added to the form fields in the customer details page and simply needs to confirm them. This significantly reduces friction in the flow.

This flowchart explains which of the above methods you would use for various situations:

Billing Request Prefilling workflow choices

This doc explains how to prefill customer details using each of these approaches before sending someone into a Billing Request Flow.

Create a Billing Request

Create a Billing Request for whatever resources you want to create - our example will ask for a payment of £5. Omitting a customer ID means we’ll create a new, blank customer linked against the request.

Use the Create a Billing Request endpoint:

POST /billing_requests
{
  "billing_requests": {
    "payment_request": {
      "currency": "GBP",
      "amount": "500",
      "description": "Large pot of Marmalade"
    }
  }
}

You will receive a full Billing Request, and the new customer and customer billing details will be linked against it.

It will look like this:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "mandate_request": null,
    "payment_request": {
      "currency": "GBP",
      "amount": "500",
      "description": "Large pot of Marmalade"
      "scheme": "faster_payments"
    },
    "links": {
      "customer": "CU00016VR36GVW",
      "customer_billing_detail": "CBD000010M15PAC"
    }
  }
}

Provide details you wish to prefill

If we know our customer’s name is Paddington Bear, we can provide those details via the Collect Customer Details endpoint.

Using the ID of the Billing Request we just created:

POST /billing_requests/BRQ123/actions/collect_customer_details
{
  "data": {
    "customer": {
      "given_name": "Paddington",
      "family_name": "Bear",
      "email": "paddington@bearthings.com"
    },
    "customer_billing_detail": {
      "address_line1": "32 Windsor Gardens",
      "city": "London",
      "postal_code": "W9 3RG",
      "country_code": "GB"
    }
  }
}

This returns the Billing Request:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "mandate_request": null,
    "payment_request": {
      "description": "Large pot of Marmalade",
      "currency": "GBP",
      "amount": 500,
      "scheme": "faster_payments",
      "links": {},
      "metadata": {}
    },
    "links": {
      "customer": "CU00016VR36GVW",
      "customer_billing_detail": "CBD000010M15PAC"
    },
    "actions": [
      {
        "type": "collect_customer_details",
        "required": true,
        "completes_actions": [],
        "requires_actions": [
          "choose_currency"
        ],
        "status": "completed",
        "collect_customer_details": {
          "incomplete_fields": {
            "customer": [],
            "customer_billing_detail": []
          }
        }
      },
      ...,
    ],
    "resources": {
      "customer": {
        "id": "CU00016VR36GVW",
        "created_at": "2021-04-08T14:06:30.977Z",
        "email": "paddington@bearthings.com",
        "given_name": "Paddington",
        "family_name": "Bear",
        "company_name": null,
        "language": "en",
        "phone_number": null,
        "metadata": {}
      },
      "customer_billing_detail": {
        "id": "CBD000010M15PAC",
        "created_at": "2021-04-08T14:06:30.997Z",
        "address_line1": "32 Windsor Gardens",
        "address_line2": null,
        "address_line3": null,
        "city": "London",
        "region": null,
        "postal_code": "W9 3RG",
        "country_code": "GB",
        "swedish_identity_number": null,
        "danish_identity_number": null
      }
    }
  }
}

Note that the embedded customer resource contains the prefilled customer details that have been provided. Also note that the collect_customer_details action is in the completed state.

Create a Billing Request Flow

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": {
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

This returns the Billing Request Flow:

{
  "billing_request_flows": {
    "id": "BRF000012CV7SZN9ZJC3S27AAZ1JFWCW",
    "auto_fulfil": true,
    "redirect_uri": null,
    "authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=BRF000012CV7SZN9ZJC3S27AAZ1JFWCW",
    "lock_customer_details": false,
    "lock_bank_account": false,
    "expires_at": "2021-05-14T15:34:44.693Z",
    "created_at": "2021-05-07T15:34:44.707Z",
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

If the customer visits the authorisation_url, they will will be taken directly to the bank select stage thus skipping the collect customer details step since this has been completed for them already.

Final note

It’s worth noting that this same functionality means customers who leave the flow and come back later will resume from where they left off.

Need help?

Connect as a partner