Billing Requests and Billing Request Flows is in early access, and subject to
Contact firstname.lastname@example.org to register your interest.
This guide explains common use cases for the Billing Request Flow - GC’s new hosted redirect flows built on top of the new Billing Request API.
Billing Request Flows (BRFs) are intended for those who wish to take instant bank payments, mandates, or a combination of both with minimal effort and without having to worry about the complexities of manually building the full integration themselves.
A Billing Request Flow at its simplest is a GC controlled flow that takes a payer through the steps required to complete a Billing Request.
You can simply take an existing Billing Request and create a flow via the API - within the returned data is an authorisation_url that you can redirect a user at for them to complete.
Depending on the state of the Billing Request there may be a number of required actions that need to be completed in order to finish the flow. Knowing which actions still need completing allows us a number of different “entry points” into the flow - allowing us to skip unneeded steps.
At a very high level a billing request flow can consist of up to 5 top-level components (you can think of these as “pages” a user might see although there might be multiple steps within a single component):
The most important part of creating a billing request is deciding whether you wish to collect a single payment, set up a mandate, or do both.
Depending on what you choose will change the details we are required to collect and the steps the payer will go through in the flow.
You can read more about how to create and configure the Billing Request and Flows in our guides.
When creating the Billing Request Flow there are a number of options you can pass in which let you configure certain aspects of flow, such as whether the payment or mandate should only be created against existing details.
lock_customer_details- if there is an existing customer attached to the billing request we will not let the user edit these details
lock_bank_account- if there is an existing bank account attached to this billing request we will not let the user create a new bank account to use instead
redirect_uri- the uri you wish the payer to be redirected to once they have completed the flow successfully
To create a flow you call the API with some of these options and include the
billing request in the
Once you have the response you can simply redirect the user to the
authorisation_url we return you.
As mentioned before if certain actions are already completed, or can be completed by another required action then we can skip them. The most common cases where a component may be skipped in the flow are as follows:
- Customer already exists - in this case we do not show the CollectCustomerDetails page however the user may be allowed to edit these details unless the customer has been locked (see locking components)
- 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)
- Bank authorisation allows collection of bank - in this case if there are no existing bank we will not ask the user to pick the bank account, instead we use the details returned from the BankHandoff stage to create it
Existing customer or bank 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.
Along with knowing the customers 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_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.
The following section explores each of the components in more detail and highlights any subtleties around how and when they might be used as part of a flow. We also link back to the relevant actions within the Billing Request API so as to tie together how we consume our own API.
Note: this screen is skipped if the details already exist, or the customer details have been locked.
If there is a pending action to collect_customer_details then this page will collect whichever relevant details we require in order to complete the billing request.
For an instant bank payment this will be relatively light touch, for a mandate this may involve more details in order to remain scheme compliant (such as billing address, identity numbers etc).
Note: this screen is skipped if the details already exist or the bank account is locked.
If there is a pending action to collect_bank_account then this page will be shown to collect the required bank account in order for GC to take a payment.
If there is also a pending required bank_authorisation action that is able to complete the collect_bank_account_details action this screen may be skipped and instead we will take the information from the bank authorisation to create this bank account. Think of this as the user is providing us the bank account details by logging in to their bank via Open Banking.
Note: currently only AIS (account information services - an open banking implementation that allows a payer to confirm ownership of an account) for creating mandates will be able to complete the collect_bank_account action and as such this screen will typically be shown for instant bank payments. This may change in the future.
Once all the details have been collected we need to confirm the payers consent and, depending what we are trying to complete with our billing request, hand off to the payers bank.
If you are trying to take an instant bank payment, or wish to verify that a payer owns a bank account before setting up a mandate there will be a pending action to complete a bank authorisation.
Depending on the type of Billing Request we may need to collect the institution we are triggering a payment with, show appropriate regulatory messages, and once the authentication is complete show a success page that the payment or mandate was completed before redirecting the payer.
This forms 3 possible subcomponents:
Note: this screen is skipped if we are able to determine the institution for the given bank account.
When taking an instant bank payment we need to know which institution or bank we are going to make the request to. We will make the best effort to guess this based on previous interactions but sometimes we cannot tell from the given bank exactly which institute we are talking to.
In this case this screen is shown to the user and they can search and select the right institute for their bank account.
This page is always shown.
It contains the details the user has input (or that have been pre-selected when creating the Billing Request) and serves as the final checkpoint before we attempt to take money and/or set up any mandates.
It serves as a good point to confirm with the user that any details they have entered are correct and to allow them to go back and change them (so long as that resource is not locked).
We will also show any documentation, legal requirements or regulatory messages in order to be compliant for the payment or mandate at this stage.
Depending on if you are on Desktop (left) or Mobile (right) you may be presented with a QR code (to scan and offload to mobile) or simply a button (which will directly launch your app on a mobile device).
Once you click the link or scan the barcode from the consent page you are redirected in a new window towards your bank.
This link varies depending on which institution we are talking to but will generally trigger the users app on their mobile device allowing them to quickly and easily give permission for the payment, or authorisation to occur.
An example of scanning a QR code on mobile to trigger the mobile app:
Depending on whether the Billing Request Flow was for a payment, mandate, or both - we typically need to show confirmation of what happened and if it was successful.
As mentioned above the previous pages will poll for the status of the billing request, and once it has reached “fulfilled” we will display a success screen summarising what was created:
Following the success page - if a redirect_url has been set we will push the user towards that link. The idea being you can return the user to your own pages and will be able to confirm by querying the Billing Request that a payment has been taken successfully.