Billing Request: Setting up a mandate - Using the Drop-in

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

This guide shows how to create a Direct Debit mandate with Billing Requests, sending the customer through a GoCardless hosted Billing Request Flow to fulfil the request.

Also, please be aware that if you submit the verify setting, payers may be asked to verify themselves if GoCardless deems them risky or if scheme compliance requires it. Read more about using verified mandates here.

Creating a Billing Request

Create a Billing Request that specifies the type of mandate you wish to create via the mandate_request field.

Mandates are created against a payment scheme. Most integrators will only care about the currency that the mandate enables charging. We recommend specifying a currency and omitting the scheme, allowing GoCardless to pick the best scheme for that currency.

Most integrators will use Billing Requests to create a mandate alongside a new customer, so we’ll use that as our example. If you want to create a mandate against an existing customer, just specify the customer ID in links.customer.

 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"
    ]
  ]
]);

You’ll receive a full Billing Request, including things like actions and resources.

It will look like this, some detail omitted:

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

The Billing Request is currently pending, meaning we need to complete the outstanding actions before it can be fulfilled. We can use Billing Request Flows to generate a checkout flow that guides the payer through these actions.

Integrators building custom payment pages should read the Billing Request actions to understand what actions are available, and how to complete them.

If you complete actions yourself, you can resume this guide to have Billing Request Flows complete whatever remains.

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/flow/static/billing_request?id=<br_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"} />
  );
};