Responding to Billing Request events

This doc shows the events that are 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.

Events and webhooks

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

Now you know about events and how to use them, we can explain what events are available for Billing Requests.

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:

`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.

More detail on events

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.

{
  "id": "EV0039FK74X5Y4",
  "created_at": "2021-05-03T18:23:08.141Z",
  "resource_type": "billing_requests",
  "action": "created",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "payer",
    "cause": "billing_request_created",
    "description": "This billing request has been created."
  },
  "metadata": {}
}

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.

{
  "id": "EV0039FK756APS",
  "created_at": "2021-05-03T18:23:08.181Z",
  "resource_type": "billing_requests",
  "action": "flow_created",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request_flow": "BRF000011RGT7FDRW90FTGJ1BZ6944DP",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "payer",
    "cause": "billing_request_flow_created",
    "description": "A billing request flow has been created against this billing request."
  },
  "metadata": {}
}

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.

{
  "id": "EV0039FK76YFFR",
  "created_at": "2021-05-03T18:23:09.435Z",
  "resource_type": "billing_requests",
  "action": "flow_visited",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request_flow": "BRF000011RGT7FDRW90FTGJ1BZ6944DP",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "payer",
    "cause": "billing_request_flow_visited",
    "description": "The billing request flow has been visited."
  },
  "metadata": {}
}

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.

{
  "id": "EV0039FK77ARRT",
  "created_at": "2021-05-03T18:23:20.386Z",
  "resource_type": "billing_requests",
  "action": "collect_customer_details",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request_flow": "BRF000011RGT7FDRW90FTGJ1BZ6944DP",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "api",
    "cause": "billing_request_collect_customer_details",
    "description": "Customer details have been collected for this billing request."
  },
  "metadata": {}
}

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.

{
  "id": "EV0039FK7845W0",
  "created_at": "2021-05-03T18:23:32.065Z",
  "resource_type": "billing_requests",
  "action": "collect_bank_account",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request_flow": "BRF000011RGT7FDRW90FTGJ1BZ6944DP",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "api",
    "cause": "billing_request_collect_bank_account",
    "description": "Bank account details have been collected for this billing request."
  },
  "metadata": {}
}

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.

{
  "id": "EV0039FK79TA5M",
  "created_at": "2021-05-03T18:24:00.063Z",
  "resource_type": "billing_requests",
  "action": "bank_authorisation_denied",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "bank_authorisation": "BAU000012N3A4GG",
    "institution_id": "monzo",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "payer",
    "cause": "billing_request_bank_authorisation_denied",
    "bank_account_id": "BA0000QF3HBM4V",
    "description": "A bank authorisation for this billing request has been denied by the payer."
  },
  "metadata": {}
}

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.

{
  "id": "EV0039FK7ATXFE",
  "created_at": "2021-05-03T18:24:26.509Z",
  "resource_type": "billing_requests",
  "action": "bank_authorisation_authorised",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "bank_authorisation": "BAU000012N4B63N",
    "institution_id": "monzo",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "payer",
    "cause": "billing_request_bank_authorisation_authorised",
    "bank_account_id": "BA0000QF3HBM4V",
    "description": "A bank authorisation for this billing request has been authorised by the payer."
  },
  "metadata": {}
}

Triggered when the Billing Request has been fulfilled, and the sub-resources have been created. This means any Instant Bank Payments have been created, along with any DD mandates from the Billing Request.

{
  "id": "EV0039FK7F2AAD",
  "created_at": "2021-05-03T18:24:26.988Z",
  "resource_type": "billing_requests",
  "action": "fulfilled",
  "links": {
    "customer": "CU00016Y7P8FPA",
    "customer_bank_account": "BA0000QF3HBM4V",
    "payment_request_payment": "PM000SY3392D1T",
    "billing_request": "BRQ000012HQV2J4"
  },
  "details": {
    "origin": "gocardless",
    "cause": "billing_request_fulfilled",
    "description": "This billing request has been fulfilled, and the resources have been created."
  },
  "metadata": {}
}

What’s next?

Reconciling payouts

Get started

Billing Request overview

First instant payment with mandate Direct Debit set up

Collect Verified Mandates

Collect Direct Debit Mandates

For partners

Go to Partner PortalTo learn more about technical and UX requirements

Need help?

Connect as a partner