Guides

Create a Billing Request and Billing Request Flow via the API (same as Hosted Pages)
Include the GoCardless Drop-in JavaScript library on your page
Initialise the component with the flow ID
The component renders the payment flow inline on your page
Listen for completion events and webhooks

Customisation:

Style the component to match your brand colours and fonts
Control the container element and placement
Handle events (success, exit, error) in your application code

Step-by-step guide

The Billing Request defines what you're collecting.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequests()->create([
  "params" => [
    "mandate_request" => [
      "scheme" => "bacs"
    ]
  ]
]);

Response:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "payment_request": null,
    "mandate_request": {
      "currency": "GBP",
      "scheme": "bacs"
    },
    "links": {
      "customer": "CU00016WDAM7BS",
      "customer_billing_detail": "CBD000010PDF4WD",
      "mandate_request": "MRQ123",
      "organisation": "OR123"
    },
    "actions": [
      {
        "type": "collect_customer_details",
        "status": "pending",
      },
      {
        "type": "collect_bank_account",
        "status": "pending"
      }
    ]
  }
}

This generates the hosted URL where the customer completes authorisation.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequestFlows()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "exit_uri" => "https://my-company.com/exit",
    "links" => [
      "billing_request" => "BRQ000010NMDMH2"
    ]
  ]
]);

UX Preview

Response:

{
  "billing_request_flows": {
    "authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=<brf_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"
    }
  }
}

Include the GoCardless Drop-in script on your page and initialise it with the billing_request_flow_id from the previous step.

<!-- Container for the Drop-in component -->
<div id="gc-dropin-container"></div>

<script src="https://pay.gocardless.com/billing/static/dropin/v2/initialise.js"></script>
<script>
  GoCardlessDropin.create({
    billingRequestFlowID: "BRF0000201",
    environment: "live",
    onSuccess: function(billingRequest, billingRequestFlow) {
      // Flow completed — verify outcome via webhook, not this callback
      console.log("Flow completed", billingRequest.id);
    },
    onExit: function(error, metadata) {
      // Customer closed the component before completing
      if (error) { console.error("Drop-in error", error); }
    }
  }).mount("#gc-dropin-container");
</script>

Event	Meaning	What to do
billing_requests.fulfilled	Customer completed the flow	Record the mandate_id from links.mandate_request_mandate
mandates.active	Mandate is ready to collect against	Enable payment collection in your system
payments.confirmed	A payment against the mandate was collected	Mark the associated period/invoice as paid
payments.failed	A payment failed	Notify the customer, retry if appropriate
mandates.cancelled	Mandate was cancelled	Stop future payment creation

Pre-collecting customer details Optional

If you already have the customer's name, email, and address, submit them before creating the flow. The hosted page skips those fields or locks them if you prefer.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequests()->collectCustomerDetails("BR123", [
  "params" => [
    "customer" => [
      "email" => "paddington@bearthings.com"
      "given_name" => "Paddington",
      "family_name" => "Bear"
    ],
    "customer_billing_detail" => [
      "address_line1" => "32 Windsor Gardens",
      "city" => "London",
      "postal_code" => "W9 3RG",
      "country_code" => "GB"
    ]
  ]
]);

Response: Updated Billing Request with collect_customer_details marked completed.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequests()->collectBankAccount("BRQ000010NMDMH2", [
  "params" => [
    "account_number" => "55779911",
    "branch_code" => "200000",
    "account_holder_name" => "Frank Osborne",
    "country_code" => "GB"
  ]
]);

Response: Updated Billing Request with collect_bank_account marked completed.

Need help?

Connect as a partner

Guides

Javascript Drop-in Flow

What is the JavaScript Drop-in Flow?

Best for:

How it works

Step-by-step guide

Create a billing request

Create a billing request flow

Initialise the Drop-in Component

Handle Webhooks

Pre-collecting customer details Optional

Collect customer details (optional)

Collect bank account (optional)