Variable Recurring Payments

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 Variable Recurring Payments (VRP) mandate

Engineering complexity - Easy

Time taken - 15 minutes

The mandate (the OBIE refers to this as “consent”) is the agreement that you create with a customer and use to create future payments against. Most integrators will use Billing Requests to create a mandate alongside a new customer, so we’ll use that as our example. To set up a mandate, use the mandate_request field when creating your Billing Request.

Please keep in mind that the requirements below should be met to create a VRPs mandate successfully:

the scheme is stated as faster_payments
the sweeping attribute is set to true
the constraints object is passed

Sweeping

This attribute is required to create a Variable Recurring Payment mandate that will be used solely for moving (or sweeping) money from one of the payer's accounts to another of the payer's accounts.

If this value is not set, we assume the billing request was created for a more generalised variable recurring payment use-case that we do not currently support, resulting in a validation error.

Constraints

constraints specify the limits on recurring payments. We can continue to take payments without the payer needing to provide consent every time as long as they are within the constraints stated during the set up of the VRP mandate.

You can set the following parameters:

start_date - the date from which the consent will be valid. It will be shown to a payer to confirm and hence should be considered in the payer timezone. This date cannot be older than the date when the payer authorises the consent. Therefore if you want to specify it, make sure that it is not in the past and that the payer has enough time to complete the flow before the date will come.
end_date - the date after which we will not be able to collect payments, as the consent stops being valid. It will be shown to a payer to confirm and hence should be considered in the payer timezone. This date cannot be in the past or older than the start date.
max_amount_per_payment - maximum amount that can be charged for a single payment.
periodic_limits - frequency configuration
- period - repeating time frame presented as "year", "month", "week" or "day".
- max_total_amount - maximum total amount that can be charged for all payments in the period.
- max_payments - maximum amount of payments that can be taken within a period
- alignment - Specifies whether the period starts when the mandate is created or lines up with a calendar date. When the period alignment is calendar based, the first payment is pro-rated to the number of remaining days from the start of the period. By default, this is set to mandate creation_date.

Use the Create a Billing Request endpoint:

POST https://api.gocardless.com/billing_requests HTTP/1.1
{
   "billing_requests": {
       "mandate_request": {
           "scheme": "faster_payments",
           "sweeping": true,
           "constraints": {
               "start_date": "2030-06-27",
               "max_amount_per_payment": 500,
               "periodic_limits": [{
                   "period": "month",
                   "max_total_amount": 10000,
                   "max_payments": 2,
                   "alignment": "creation_date"
               }]
           }
       }
   }
}

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

It will look like this:

{
 "billing_requests": {
     "id": "BR123",
     "status": "pending",
     "mandate_request": {
         "currency": "GBP",
         "scheme": "faster_payments",
     },
     "payment_request": null,
     "metadata": null,
     "links": {
         "customer": "CU123",
         "customer_billing_detail": "CBD123",
         "creditor": "CR123",
         "organisation": "OR123",
         "mandate_request": "MRQ123"
     },
     "creditor_name": "Hotel Park Grand",
     "actions": [
         {
             "type": "collect_customer_details",
             "required": true,
             "status": "pending",
         },
         {
             "type": "collect_bank_account",
             "required": true,
             "status": "pending"
         },
         {
             "type": "bank_authorisation",
             "required": true,
             "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.

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