GoCardlessDeveloper Docs
Create a sandbox account

Custom Payment Page Tools#

View as Markdown

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#

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 Pay By Bank 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:

  1. A valid Billing Request Id to display elements and content dependent on the bank scheme.
  2. 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.

NameTypeDefaultDescription
parentIdstringThe component will be attached as the last child of document.bodyId 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 });
}
}
<script>
export default {
setup() {
return {
parentId: `gc-compliance-${Math.random().toString(20).substring(2, 6)}`,
};
},
mounted() {
window.GoCardlessCompliance.render("BRQ123", "bank-authorisation", { parentId: this.parentId });
},
};

</script>

<template>
<div :id="parentId"></div>
</template>
<script>
import { onMount } from "svelte";

const parentId = `gc-compliance-${Math.random().toString(20).substring(2, 6)}`;
onMount(() => {
window.GoCardlessCompliance.render("BRQ123", "bank-authorisation", { parentId });
});

</script>

<div id={parentId}></div>
import { useRef, useEffect, useState } from "react";

export const Compliance = () => {
const mounted = useRef(false);
const [parentId] = useState(getRandomId());

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#

ErrorReasons
A valid billingRequestId is requiredYou 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 documentWe 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 detailsWe 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.

What's next?#

Billing Requests

Learn how Billing Requests power custom payment pages.

Learn more
GoCardless CLI

Build, test, and manage your GoCardless integration from the terminal.

Learn more
SupportDashboard