Prefilling customer details#

View as Markdown

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.

Collect Customer Details endpoint — Creates a fully pre-populated customer record so the customer skips the details page. Requires GoCardless Pro or GoCardless Enterprise with the custom payment pages upgrade.
Existing customer record — Link an existing customer ID to the Billing Request. The customer's details are already known and they skip the customer details page entirely.
Billing Request Flows API — Pass prefilled values into the Billing Request Flow. The customer sees their details pre-populated in the form and only needs to confirm them.

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.

What's next?#

Prefill with Existing Customer

Link an existing customer record to skip the customer details step entirely.

Learn more

Prefill into Billing Request Flow

Pass prefilled values directly into the checkout flow.

Learn more