Billing Request Events#
This page covers the events produced as part of a Billing Request's lifecycle, and how you can use them to understand how your customers are behaving across your requests.
When things happen in GoCardless's system, we create an event to record that it happened. You can browse your events in the dashboard or via the API.
Integrators who want to respond to events as they happen can follow the Staying up-to-date with webhooks guide, where you configure a webhook endpoint to receive events as they happen.
Billing Request events#
Billing Requests are the touchpoint between a merchant and their customer, and everyone can benefit from a high level of visibility into the process. For this reason, we aim to provide events for:
Billing Requests are the touchpoint between a merchant and their customer, and everyone can benefit from a high level of visibility into the process. For this reason, we aim to provide events for:
- Whenever any state in the Billing Request changes
- Payer interactions, such as opening a Billing Request Flow link
- Any situations that might require contacting the payer, such as bank authorisation failure
Each event aims to reference every resource that might be relevant. Across the events, we have the following link fields:
| Resource | Description |
|---|---|
billing_request | The billing request ID |
billing_request_flow | The flow that triggered the event, if from a flow |
customer | Associated customer ID |
customer_bank_account | Whatever bank account is associated with the event |
bank_authorisation | whatever bank authorisation is associated with the event |
institution_id | whatever institution associated with the event |
payment_request_payment | payment ID that was created as part of the request |
mandate_request_mandate | mandate ID that was created as part of the request |
We'll split this section into a header per event, with a small explanation of what the event does. We'll include an example event in the same format you'd see from the List Events endpoint, or what you'd receive in a webhook.
billing_request_created#
Triggered whenever a Billing Request is created. Use this event to register a Billing Request, so that any listening system can respond to subsequent events that follow.
The origin can be api if created through an integration, or payer if created as part of a payer's action, like following a paylink or a Billing Request Template URL.
billing_request_flow_created#
Triggered when a new flow has been created against a Billing Request. This does not mean anyone has visited the flow, just that a flow has been created.
billing_request_flow_visited#
When the Billing Request Flow link is visited, the frontend app will initialise a new session in exchange for the Billing Request Flow ID.
This is the first thing that happens upon visiting the flow and will trigger the creation of this event. You can use this event to infer that a payer has visited the flow.
billing_request_collect_customer_details#
Triggered whenever a payer successfully completes the collect_customer_details action. Can be used to build funnels to measure how payers progress through the flow.
billing_request_collect_bank_account#
Triggered whenever a payer successfully completes the collect_bank_account action. Can be used to build funnels to measure how payers progress through the flow.
The customer_bank_account ID is the bank account that was created as a result of completing this action.
billing_request_bank_authorisation_denied#
Triggered if a payer was redirected to their bank and rejected the authorisation. Payers can always return to the flow and create a new bank authorisation, but the linked authorisation is now permanently denied.
billing_request_bank_authorisation_authorised#
Triggered if a payer was redirected to their bank and authorised the request. Authorisation of payments can trigger Billing Request fulfilment, depending on the scheme.
billing_request_fulfilled#
Triggered when the Billing Request has been fulfilled, and the sub-resources have been created. This means any Pay By Banks have been created, along with any DD mandates from the Billing Request.
What's next?#
Understand how Pay By Bank payments trigger billing request events.
Events are also fired during mandate setup via Billing Requests.
Events fired after mandate creation: active, cancelled, failed, expired.
How to configure a webhook endpoint and verify webhook signatures.