Billing Request (PayTo feature)

Billing Request Actions

Whenever you create a Billing Request, it will have a list of actions that require completion before it’s possible to fulfil the request.

The possible actions are:

• collect_customer_details, collect customer details required for the schemes

• collect_bank_account, create the bank account for the mandate/payment

• bank_authorisation, have the payer authorise the billing request via their bank if required

• confirm_payer_details, confirm customer and bank account details provided by the payer

Once all required actions have been completed, the Billing Request will fulfil automatically.

Which actions should I implement?

Even if integrators complete a selection of actions themselves, Billing Request Flows can be used to complete the remaining actions.

Our recommendations for whether integrators should implement each action are:

• collect_customer_details, implement this if you want a white label flow to collect customer details or have already collected the details (prefilling, etc)

• collect_bank_account, as with customer details, but be aware that Billing Request Flows can avoid this step for certain schemes which can improve conversion by reducing the number of details a payer has to manually input

• confirm_payer_details, this action is not required for PayTo.

• bank_authorisation, implement this as the final step

The actions presented on a Billing Request are unordered, but each action may have dependencies, or have other actions depending on it.

These are specified in the fields completes_actions and requires_actions.

Taking a bank_authorisation as an example:

Action status is either pending or completed.

requires_actions: Actions can only be executed if the actions listed in requires_action have been completed- in this example, we can’t complete the bank authorisation until we’ve collected the bank.

completes_actions: Actions can complete other actions, which can help streamline checkout flows. The example shows how a bank authorisation might collect customer details, completing that action as a side effect.

For most integrators, we suggest building flows that process actions in the order of:

1. collect_customer_details, so customer contact details are prioritised

2. collect_bank_account, if it is required and another action won’t complete it

3. bank_authorisation, as the penultimate step before completing the checkout flow

4. confirm_payer_details, only applicable if it is a mandate_request

Action: collect_customer_details 

Billing Requests aim to create billing resources against a customer, either a mandate (PayTo or Direct Debit), an Instant Bank Payment, or both.

Payment schemes vary in what customer details you are required to collect. The collect_customer_details action is about collecting all the details required by either the mandate or the payment scheme, to ensure we meet regulatory needs.

As an example, we can create a Billing Request for a AUD mandate:

This returns a Billing Request that looks like this:

Note that:

• There is a collect_customer_details action, which is pending

• A new customer has been created for us, as the Billing Request wasn’t attached to an existing customer

• The customer resource is presented back to us, and they have no filled fields

• The collect_customer_details action is designed to help us collect the required information from our customers.

Taking a closer look at the action:

The collect_customer_details.incomplete_fields object tells us what fields we need to collect, for both resources. Which fields are required changes depending on the schemes of the mandate (or payment).

We can complete this action by POST’ing to the Collect customer details for the billing request endpoint:

As with all action endpoints, the response is the Billing Request. What we get back is:

Note that:

• The collect_customer_details action is now completed, meaning we can move on to other actions

• As a result of us collecting the details, our customer and customer_billing_detail has been populated with the details we collected

Most integrators will collect these details via web forms, filled by their payers. Integrators are expected to build forms that can collect all possible customer and customer_billing_detail fields (see the Collect customer details schema) but only display the inputs required, as per incomplete_fields.

Depending on the scheme, we might need to collect bank account details before fulfilling the Billing Request. An example is a PayTo mandate, where we need to capture the payer’s bank in order to create payments against them.

As an example, we can create a Billing Request for a PayTo mandate:

This returns a Billing Request that looks like this:

Note that:

• There is a collect_bank_account action that is pending

• We have no links.customer_bank_account, confirming no bank account is attached

We can complete this action by POST’ing to the Collect bank account for the billing request endpoint:

As with all action endpoints, the response is the Billing Request. What we get back is:

Note that:

• The collect_bank_account action is now completed, meaning we can move on to other actions

• As a result of us collecting the bank account, we have created a customer_bank_account resource and you can see the links.customer_bank_account ID has been set

We advise most integrators use Billing Request Flows to complete this action, as the hosted flows will try skipping this action if it can be fulfilled by another (such as bank authorisation).

To authorise the PayTo mandate, the payer needs to log in to their bank. This is initiated by the bank_authorisation. 

In other words, hitting the bank_authorisation endpoint will trigger the creation of the PayTo mandate which is the final action required. The rest is up to the payer. As an example, we can create a Billing Request for PayTo:

This returns a Billing Request that looks like this:

Preventing Breaking changes

In order to automatically receive new features and always remain scheme compliant without having to change your integration, GoCardless will need to adjust actions by adding new actions or making optional actions required. This means it will break your integration if you don’t fall back to Billing Request Flow. Therefore if you are building custom payment pages you needs to Implement the actions you are aware of and want to process.