Billing Request (Instant Bank Pay feature)

Using the JavaScript Drop-in

This guide shows how to use the Javascript Drop-in to allow customers to complete the Billing Request Flow without leaving the integrator’s site.

Use the Drop-in when you already have a frontend website, and want to benefit from having customers stay on your site, and avoiding site-to-site redirects.

Preview the React Drop-in

Create

Goal - Create a Direct Debit mandate using Billing Request

Engineering complexity - Easy

Time taken - 15 minutes

Use the Create a Billing Request endpoint:

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

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

This will create a new Billing Request, asking for a Bacs mandate and requesting a when_available verification preference.

The response will look like this:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "mandate_request": {
      "currency": "GBP",
      "scheme": "bacs",
      "verify": "when_available"
    },
    "actions": [
      {
        "type": "bank_authorisation",
        "required": true,
        "status": "pending"
      }
    ]
  }
}

As Bacs supports verification, you’ll see we have a bank_authorisation action in the Billing Request response. Note the action is required, which means we cannot fulfil this request without first completing the bank authorisation.

We can use Billing Request Flows to generate a checkout flow that guides the payer through these actions, including the verification via bank authorisation.

Goal - Create a Billing Request Flow that can be used for your customer to authorise payments

Engineering complexity - Easy

Time taken - 15 minutes

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:

$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

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

You will need to store a reference to the Billing Request and Billing Request Flow ID, often against an internal customer record.

// Handler is an instance of the Dropin, with methods
// open, exit, etc.
//
// You must call open() before the Dropin will activate.
//
// You can pass one of either billingRequestFlowID or billingRequestTemplateID.
const handler = GoCardlessDropin.create({
    billingRequestFlowID: "<generated-on-backend>",
    // billingRequestTemplateID: "BRT123",
    environment: "live", // either live or sandbox
    onSuccess: (billingRequest, billingRequestFlow) => {},
    onExit: (error, metadata) => {},
});

When using Javascript, GoCardlessDropin.create returns an Object with two functions, open and exit.

With React, the useGoCardlessDropin hook returns an Object with four values, open, exit, ready and error. open and exit behave just as above.

The ready value will be true once the Drop-in has been loaded and the open function is ready to be called. You should watch error for any issues that occurred that prevented the Drop-in from properly loading.

open()

Calling open will attach the Drop-in iframe to the DOM, and open the modal ready for a customer to complete the flow. Follow the progress of the customer via the onSuccess and onExit handlers.

const handler = GoCardlessDropin.create({
    billingRequestFlowID: "<generated-on-backend>",
    environment: "live", // either live or sandbox
    onSuccess: (billingRequest, billingRequestFlow) => {},
    onExit: (error, metadata) => {},
});

// Create handler as above
const handler = GoCardlessDropin.create({/* ... */});

// Open the Dropin modal, making it visible to the customer
handler.open();

exit()

Calling exit will close the Drop-in, removing the modal from the DOM.

If the customer had successfully completed the flow, this will trigger the onSuccess callback. Otherwise, the onExit callback is triggered with a null error.

onSuccess

onSuccess receives the Billing Request that has been worked.

This is called when the flow exits successfully. Depending on how the flow was configured, it may have completed but not fulfilled the Billing Request - check the status of the request before assuming it has been fulfilled.

onExit

onExit is called with two arguments: an error Object and a metadata Object.

The onExit callback is called when the customer leaves the flow before completion. This can happen when they voluntarily leave the flow, or due to an unexpected error within it.

The error object is null if no error was encountered, such as when a customer clicks the exit button. Otherwise it is set to the error that caused the flow to fail.

The metadata object is populated with contextual information that can help understand the source or cause of the error.

React Drop-in Example

import React, { useCallback, useState } from "react";
import {
  useGoCardlessDropin,
  GoCardlessDropinOptions,
  GoCardlessDropinOnSuccess,
} from "@gocardless/react-dropin";

// Display a button that opens the Dropin on click, starting a checkout
// flow for the specified Billing Request Flow.
const DropinButton = (options: GoCardlessDropinOptions) => {
  const { open } = useGoCardlessDropin({ ...options });

  return (
    <button type="button" onClick={() => open()}>
      Start Dropin for <code>{options.billingRequestFlowID}</code> in{" "}
      <code>{options.environment}</code>
    </button>
  );
};

// Example checkout flow, where we create a Billing Request Flow ID by talking
// with our backend API.
const App: FunctionComponent = () => {
  const [flowID, setFlowID] = useState<string | null>(null);

  // Build your backend with an API endpoint that:
  //
  //   1. Creates a Billing Request for the resources you wish to create
  //   2. Create a Billing Request Flow against (1)
  //   3. Return the ID from (2)
  //
  // See an example of this at Taking an Instant Bank Payment:
  // https://developer.gocardless.com/getting-started/billing-requests/taking-an-instant-bank-payment/
  React.useEffect(() => {
    async function createFlow() {
      // Expecting a JSON body like:
      // {
      //   "flow_id": "BRF123456"
      // }
      let response = await fetch("/api/flows", {
        method: "POST",
      });
      const { flow_id } = await response.json();
      setFlowID(flow_id);
    }
    createFlow();
  }, []);

  // Only show the button once we have a Billing Request Flow ID
  return flowID === null ? (
    <div className="loader"></div>
  ) : (
    <DropinButton billingRequestFlowID={flowID} environment={"live"} />
  );
};