Custom Payment Page Tools

Custom Payment Page Tools is a collection of tools designed to minimise effort in building your own payments UI powered by GoCardless billing APIs. They can be effortlessly utilised when developing a custom web UI with different JS frameworks or in mobile development with WebViews.

At the moment the following tools are available:

compliance.js

Compliance.js

Before GoCardless initiates a payment for your customer, we are legally required by the UK Payment Services Regulations to provide them with a copy of a payment service contract governing that service. This is the Payer Terms of Use doc which is linked inside Compliance.js. Additionally, when obtaining your customer's personal data, we are legally required by the UK General Data Protection Regulation to provide them with certain privacy information. This is the Privacy Notice doc which is linked inside Compliance.js. When you build your own UI, GoCardless is not able to directly provide these legal documents to the payer. So, to ensure that we do not breach any law, we are not able to sign off on your UI unless you have added Compliance.js.

It adds elements to the HTML layout of custom payment pages to make the UI compliant. For example, for bank authorisation, you must append the GoCardless legal note with Payer Terms of Use and Privacy Notice links before starting the bank authorisation process for Instant Bank Pay or Variable Recurring Payments in the UK.

Getting started

Include compliance.js with a script tag in the head section of your index.html:

<head>
  ...
  <script src="https://custom-payment-page-tools.gocardless.com/compliance.js"></script>
</head>

Once the script is loaded, your application can use the GoCardlessCompliance client, as it is added globally in window. Let's now call render:

window.GoCardlessCompliance.render("BRQ123", "bank-authorisation");

The render method requires the following parameters:

A valid Billing Request Id to display elements and content dependent on the bank scheme.
namespace to display elements and content relevant to a particular step in the flow. Available options: "bank_authorisation".

Testing

To test the integration with GoCardless Sandbox before going live, include compliance.js with the sandbox value in the environment attribute. If nothing is passed, the production environment will be used.

<script src="https://custom-payment-page-tools.gocardless.com/compliance.js" environment="sandbox"></script>

Render options

You can pass the options object to define the position of the compliance elements in your layout or change basic styles for the light/dark mode.

Name	Type	Default	Description
parentId	string	The component will be attached as the last child of `document.body`	Id of an existing HTML element in the document to render the component in.
theme	`"light"`, `"dark"`	`"light"`	The colour theme

const options = {
  parentId: "my-element-id",
  theme: "dark"
};

window.GoCardlessCompliance.render(
  "BRQ123",
  "bank-authorisation",
  options
);

Using with JS frameworks

We suggest separating the GoCardlessCompliance.render call into an independent component to be used across your application. We also recommend generating unique identifiers for the containers where compliance elements are supposed to be rendered for each instance.

import { Component } from '@angular/core';

@Component({
  selector: 'app-compliance',
  templateUrl: './compliance.component.html'
})

export class ComplianceComponent {
  parentId = `gc-compliance-${(Math.random().toString(20)).substring(2, 6)}`;
  ngAfterViewInit() {
    window.GoCardlessCompliance.render(
      "BRQ123",
      "bank-authorisation",
      { parentId: this.parentId }
    );
  }
}

import { useRef, useEffect, useState } from "react";
export const Compliance = () => {
  const mounted = useRef(false);
  const [parentId] = useState(getRandomId());

  //GoCardlessCompliance.render should only onMount
  useEffect(() => {
    if (!mounted.current) {
      window.GoCardlessCompliance.render(
        "BRQ123",
        "bank-authorisation",
        { parentId }
      );
      mounted.current = true;
    }
  }, [parentId]);

  return <div id={parentId}></div>;
}

const getRandomId = () => `gc-compliance-${(Math.random().toString(20)).substring(2, 6)}`;

import { SafeAreaView } from 'react-native';
import { WebView } from 'react-native-webview';

export default function App() {
  return (
    <SafeAreaView style={{flex: 1}}>
      <WebView
        source={{ html: `
          <html>
            <head>
              <meta name="viewport" content="width=device-width, initial-scale=1" />
              <script src="https://custom-payment-page-tools.gocardless.com/compliance.js"></script>
            </head>
            <body>
              <div id="gc-compliance"></div>
              <script>
                window.GoCardlessCompliance.render(
                  "BRQ123",
                  "bank-authorisation",
                  {parentId: "gc-compliance"}
                )
              </script>
            </body>
          </html>`
        }}
      />
    </SafeAreaView>
  );
}

Error Handling

Error	Reasons
A valid billingRequestId is required	You haven't passed a Billing Request Id in the `render` method.
Namespace must be one of ...	You haven't passed a valid namespace in the `render` method - check the available options above.
The parent element doesn't exist in the document	We haven't found any element in your `document.body` with the id passed in `options` - make sure that it is attached to the DOM tree before calling the `render` method.
GoCardless API returned an error when trying to get payment flow details	We weren't able to get payment flow details to show relevant elements: very likely you have used an invalid Billing Request Id or a valid one but for the wrong environment.

Need help?

Connect as a partner

Custom Payment Page Tools

Compliance.js

Getting started

Testing

Render options

Using with JS frameworks

Angular

Vue

Svelte

React

React Native

Error Handling