Pre-filling customer details

If you already hold information about your customers, you can provide this information via the Collect Customer Details endpoint before sending your user through a Billing Request Flow. Note that this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with custom payment pages upgrade.

When the payer visits the Billing Request Flow, the form will be prefilled with whatever data you provided. This simplifies the process providing a better customer experience which should in turn improve conversion.

This doc explains how to pre-fill customer details 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’ll 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 pre-fill

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"
    }
  }
}

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",
    },
    "actions": [
      {
        "type": "collect_customer_details",
        "required": true,
        "completes_actions": [],
        "requires_actions": [
          "choose_currency"
        ],
        "status": "pending",
        "collect_customer_details": {
          "incomplete_fields": {
            "customer": [
              "email"
            ],
            "customer_billing_detail": []
          }
        }
      },
      ...
    ],
    "resources": {
      "customer": {
        "id": "CU00016YYBRCJD",
        "created_at": "2021-05-07T15:34:38.627Z",
        "email": null,
        "given_name": "Paddington",
        "family_name": "Bear",
        "company_name": null,
        "language": "en",
        "phone_number": null,
        "metadata": {}
      }
    }
  }
}

Note that the embedded customer resource has the given_name and family_name. We still require a customer email, which is why the collect_customer_details action is still pending, with email listed in incomplete_fields.

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 begin the checkout flow asking for their customer details, but with given and family name already pre-filled:

The customer can amend any of the pre-filled information and complete those fields that haven’t been pre-filled.

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?