Variable Recurring Payments

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 -  optional  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 -  optional  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 -  required  maximum amount that can be charged for a single payment.

• periodic_limits -  required  frequency configuration

  • period -  required  repeating time frame presented as "year", "month", "week" or "day".

  • max_total_amount -  required  maximum total amount that can be charged for all payments in the period.

  • max_payments -  optional  maximum amount of payments that can be taken within a period

  • alignment -  optional 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:

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

It will look like this:

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.

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:

This returns a new flow, which has an authorisation_url you should send to your customer:

Share your authorisation link from the response in Step 02, via a button on your website, SMS, email, or any other way you like.

Preview what your customer will see by following the steps below.

Some customers may not be able to authorise the VRP mandate through the Billing Request Flow. Their bank may not support VRP yet, for instance. 

To retain these customers and let them pay another way, you may pass an Exit URI which will send them wherever you choose in order to complete the transaction. It’s as simple as providing the address you’d like us to return the customer to.

Provide an Exit URI when creating the Billing Request Flow



You may pass a exit_uri when creating the Billing Request Flow, the same way you pass the redirect_uri.

Note: We recommend that you return customers to your checkout page, at the point of choosing a payment method.

This returns a new flow which includes the exit_uri being passed:

Customers will be sent to this URI when they click on the Exit URI in the Billing Request Flow.



Customer uses the Exit URL to return to your checkout



The Exit URL is shown if the customer’s bank isn’t supported for VRP.

If you are creating a new mandate or real-time payment for an existing customer, you may let the customer skip some steps.

If you’ve seen this customer before, you may specify the customer ID in links.customer field of the Billing Request. This will result in the CollectCustomerDetails page being skipped. The user may be allowed to edit these details unless the customer has been locked (see locking components below).

A Bank account already exists- in this case, we do not show the CollectBankAccount page however the user may be allowed to create a new bank account and use that for the payment unless the bank account has been locked (see locking components)

Existing customers or banks can be attached to the Billing Request when it is created, an example of this might be when creating a “top-up” single payment for a customer you already have a relationship with. 

See API reference

Along with knowing the customer's details and the bank account you may wish to “lock” the request to only allow the customer to use those details. This allows you to ensure the payment is taken using details you have already collected for this customer in your own systems.

You can lock the customer, the bank account or both. This is done when creating the Billing Request Flow by setting lock_customer_details or lock_bank_account to true.

If a linked resource is locked the following happens:

• Customer locked - The CollectCustomerDetails page is not shown and the customer cannot open them for editing

• Bank account locked - The CollectBankAccount page is not shown and the customer cannot add another bank account to use instead

If both are locked then we skip almost every page and go directly to the confirmation page within the BankHandoff component. All the payer needs to do is confirm and possibly authenticate with the bank if it is required.

For mandate only requests, you may also "lock" the currency and scheme that the customer pays in. By default, mandate only requests have the currency/scheme "unlocked" so that the customer can set up their mandate in any of your available schemes. If you lock the currency, however, they will only be able to pay with the scheme you specified when creating the Billing Request. This can be useful if you only want to allow a customer to pay in one specific scheme.

This can be achieved by setting lock_currency to true on the Billing Request Flow. In this case a currency selector will not show in the payment page UI for the payer, and they will be unable to change currency.

The customer provides their personal details on the first screen.

The customer selects their institution in order to complete this step.

The customer has provided enough information for the transaction to be initiated with their bank. They are prompted to complete the process in their banking application. Depending on the bank they are with, they may also get a push notification to their device or an SMS.

Go to their bank to complete the authorisation. Customers can use the QR code to jump directly into their mobile banking app (this is the best UX in most cases) or opt to continue on their desktop.

Once the payer has completed the authorisation process, there is a confirmation page. All the required actions have been completed and the Billing Request is fulfilled.