The product described here is in early-access. This means the Drop-in library is exempt from our normal compatibility policy, though we hope to release it properly soon. Please get in touch (api@gocardless.com) if you're interested in trying it out.

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.

Installation

The Drop-in is a Javascript modal that allows integrators to initialise Billing Request Flows all from within their own websites.

You install the Drop-in into your frontend site, using either the plain Javascript library or React bindings.

Javascript

Install the Drop-in by adding the initialise script on each page of your site:

<script src="https://pay.gocardless.com/billing/static/dropin/v2/initialise.js"></script>

You are discouraged from bundling the initialisation script or vendoring it, as GoCardless reserves the right to make non-breaking changes to the underlying implementation, which you will want your sites to pickup automatically.

We guarantee backward compatibility between major versions of the initialise script, as denoted by the script source URL.

React

GoCardless offer a react-dropin library that provides React bindings and TypeScript definitions for the Drop-in: check the README for full details, and example implementations.

You can install the package using either npm or yarn.

With npm:

npm install --save @gocardless/react-dropin

With yarn:

yarn add @gocardless/react-dropin

Once installed, you can import the React bindings:

import {
  useGoCardlessDropin,
  GoCardlessDropinOptions,
  GoCardlessDropinOnSuccess,
} from '@gocardless/react-dropin';

Create

A typical pattern is to create the Billing Request in your sites backend server, along with a Billing Request Flow, then pass the ID of that flow to the client to create the modal.

This ensures your backend can store a reference to the Billing Request, often against an internal customer record.

// Handler is an instance of the Dropin, with methods like
// open, exit, etc.
//
// You must call open() before the Dropin will activate.
const handler = GoCardlessDropin.create({
    billingRequestFlowID: "<generated-on-backend>",
    environment: "live", // either live or sandbox
    onSuccess: (billingRequest, billingRequestFlow) => {},
    onExit: (error, metadata) => {},
});
// Use an existing Billing Request Flow ID likely generated in
// your backend, then configure hooks for Dropin lifecycle
// events.
const config : GoCardlessDropinOptions = {
    billingRequestFlowID: "<generated-on-backend>",
    environment: "live", // either live or sandbox
    onSuccess: (billingRequest, billingRequestFlow) => {},
    onExit: (error, metadata) => {},
});

// Create state variables via the useGoCardlessDropin hook
// function, to be used inside a React component render
// function.
//
// You must call open() before the Dropin will activate.
const {
    open, exit, ready, error,
} = useGoCardlessDropin(config);

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.

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

// Open the Dropin modal, making it visible to the customer
handler.open();
// Call hook as above
const { open, ready } = useGoCardlessDropin(config);

// Only open the link if the Dropin is ready
if (ready) {
  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.

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

// Closes the Dropin modal
handler.exit();
// Call hook as above
const { exit } = useGoCardlessDropin(config);

// Closes the Dropin modal
exit();

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 popluated with contextual information that can help understand the source or cause of the error.