Set up Connect under Bud's licence

Below we’ll provide you with a step-by-step guide to help you integrate Bud’s Open Banking Aggregation service when using Bud Connect. This means that you’ll be using Bud’s license (as a registered AISP) in order to provide an Open Banking Aggregation service to your Customers. As a result, you have to use Bud Connect to allow your customers to connect new account(s).

Before starting you’ll need a:

valid OAuth access token - for further details on how to authenticate to Bud’s APIs please see this guide; and
valid customer_id associated with your ‘Project’ (API Credentials). For further details on how to register a customer, please refer to this guide.

View Providers & Check Maintenance Windows

The GET /v1/open-banking/providers endpoint (here) will allow you to view the available providers supported by Bud’s Open Banking Aggregation service. Each provider object will contain a maintenance_window and maintenance_status fields. These can be used to check if a provider is currently (or soon to be) undergoing maintenance and may include a timescale for how long it will be in maintenance.

{
	"operation_id": "open_banking_providers_get",
	"data": [
		{
			"provider": "Amex",
			"regions": [
				"GBR",
				"FRA"
			],
			"display_name": "American Express",
			"icon": "https://assets.thisisbud.com/openbanking/amex-logo.png",
			"maintenance_window": null,
			"maintenance_status": "inactive"
		},
		{
			"provider": "Monzo",
			"regions": [
				"GBR"
			],
			"display_name": "Monzo",
			"icon": "https://assets.thisisbud.com/logos/Monzo/v1/[email protected]",
			"maintenance_window": null,
			"maintenance_status": "inactive"
		}
	],
	"metadata": null
}

The provider field within the response body, e.g. “provider”: “Lloyds”, shows the name of the ASPSP that your Customers can connect to. Please note that the value of this provider field is the unique identifier for the corresponding ASPSP, and it is used elsewhere within Bud’s OB Aggregation APIs.

📘
What is a maintenance window?
A maintenance window is a period of time where the provider (ASPSP) will be making changes or improvements to their service. During this time the maintenance_status will be listed as active and your customers will be unable to make a connection to these providers. When the maintenance_window is over the provider will be available to connect to.

Configure my Callback URL(s)

Clients are required to configure their Callback URL(s) in order to receive event notifications regarding the status of different tasks. In terms of Bud Connect, Bud will use your Callback URL to send requests detailing the status of different account connections and refresh tasks.

There are three different webhooks available in regard to the Open Banking Aggregation flow:

Open banking sync completed - works for both connect and refresh tasks. This will fire when an open banking connect or refresh task (in both the TSP and TPP scenarios) either completes or fails. The result field returned in the response will provide some details as to why a given task may have failed (if the status field is equal to “Failed”).
Open banking connection completed - for those who are just interested in the connect tasks (i.e. not refresh). This will fire when an open banking connect task (in both the TSP and TPP scenarios) either completes or fails. The result field will provide some details as to why a given task may have failed (if the status field is equal to “Failed”)
Open banking refresh completed - those who are just interested in the refresh tasks (i.e. not connect). This will fire when an open banking refresh task (in both the TSP and TPP scenarios) either completes or fails. The result field will provide some details as to why a given task may have failed (if the status field is equal to “Failed”)

The steps to set-up your Callback URL are as follows:

Log into the Bud developer console
Navigate to Projects
Select the project that you would like to configure the callback for
There will be a header for Webhooks that will appear within the project
Select the edit icon next to one of the relevant Open Banking Aggregation webhooks
Input your chosen URL into the text space provided.

The Callback URL specified will be used to notify you when Bud has completed (or failed) fetching the customer’s account information from the relevant ASPSP. At this point, the customer’s account information will be ready to collect via the relevant GET data endpoints (of which there are many).

❗️
Please note that all of Bud's Callbacks are sent over TLS as standard

Callback Security

All Bud webhooks are provided with an X-Signature and X-Signing-ID header. The X-Signing-ID includes the public key id which should be used to verify the X-Signaure header (i.e. the signed request body JWT). A list of public keys can be found at https://assets.thisisbud.com/bud-callback.jwks.

Callback URL vs Redirect URL

The Redirect URL is used to send the customer back to your specified page (either on mobile or on the web) after they have completed the authorisation flow via Bud Connect.
The Callback URL lets you know when a customer's account information is ready to be collected after Bud has fetched the data from the ASPSP. This can be after an initial account connection task, or after a refresh task.

Connect Account(s) via Bud Connect

The first step to allow your customers to connect to a new provider, is to make a request to the Open Banking Authorisation Gateway URL endpoint. Using the POST /v2/open-banking/authorisation-gateway-url endpoint (here), you will need to specify a redirect_url within the request payload e.g. {"redirect_url": "https://thisisbud.com/"}. Once your Customer has completed the authorisation process, they will be redirected to your specified redirect_url.

❗️
Please note that the returned authorisation-gateway-url needs to be presented to the user within one hour. After your customer has been redirected to the URL, a new token will be created and will be continually refreshed. Once the customer has selected the provider they wish to connect to, they will then have a limited time to complete the authorisation process with that provider. This time limit is three hours for all providers. Once this expiration time has been reached, you will need to obtain a new authorisation-gateway-url for that customer.

📘
If you're not registered as an agent of Bud and are acting as an ancillary, you will need to include "accounts_summary": true and "enable_account_data_management": true in all requests to the POST /v2/open-banking/authorisation-gateway-url endpoint.

Direct your customer to the Bud Connect Authorisation Gateway URL provided in the response.
- Your customer will be able to select their chosen provider from a list populated by GET providers
- The customer will then be shown the consent screen where they will agree to Bud’s data-sharing terms and conditions.
- Your customer will then be redirected to their chosen provider to authorise the connection. In a new popup window (i.e. web-to-web or app-to-web), or in some cases on mobile via the provider's relevant application (i.e. app-to-app), your customer will need to enter their banking credentials and complete the authentication process with their provider.
Having completed the authorisation flow with their provider, your customer will then be redirected back to your specified redirect_url. The status of the authorisation task will be shown within the redirect URL (as a path parameter), if ?status=success then your customer has been successfully authorised with their chosen provider. If ?status=failed then the authorisation step has failed, and the customer will need to retry the authorisation with their chosen provider. There will also be a parameter task_id included when the user is redirect back to your redirect_url which can be used in the next step.
After the user has been redirected back to your redirect url you can use the task_id parameter to check the status of the task to fetch your customers account information from the provider. This task_id can be passed to the Retrieve Connection Status GET v1/open-banking/connect/{connection_task_id endpoint (here). This endpoint should be polled using a delay taken from the next_url_delay field in the metadata object. When a connection has completed the status field will change to either "Completed" or "Failed" with the reason being stored in the result field. If the task reaches a "Completed" state you will then be able to make calls to the accounts and transactions endpoint to retrieve your customers data (as detailed in the Fetch Account Information section below.
Additionally the result of this task will be pushed to your configured Callback URL. An example request payload for an Open banking sync completed callback for a successful connection task is as follows:

{  
  "data": {  
    "task_id": "030c78b0-617c-4649-9319-e07569362a14",  
    "task_type": "connect",  
    "customer_id": "82a90a04-4bdf-446a-932e-fb559ea99c29",  
    "status": "Completed",  
    "result": "success",
    "provider": "Capital_One"
  }  
}

❗️
Please note that the account will be connected in a matter of seconds. If the connection fails, the customer will need to try again.

Fetch Account Information

To see the customer's account information you will need to use the Retrieve Accounts and Retrieve Transactions endpoints. These endpoints are used to show the accounts a customer has given their consent to connect to and the transactions of the accounts respectively.

Make sure to wait for the task to be completed before requesting data, otherwise you risk to fetch partial responses.

Use the GET /financial/v2/accounts endpoint (here) to retrieve all of your customers’ connected accounts. The results field found within the metadata object shows the number of accounts returned in the response body.
Use the GET /financial/v2/accounts/{account_id} endpoint (here) to retrieve the data for a specific account.
Use the GET /financial/v2/transactions endpoint (here) to retrieve the latest transactions for all your customers' connected accounts.

You can use the date_from and date_to query parameters (along with a huge variety of others to filter the response) to specify a timeframe. By default the endpoint will return the last three months.
You can use the account_id of your customer's account in order to return transactions for a specific account.
The transaction information is returned with various enrichments that have been applied to the data, which include (but are not limited to):
- Categorisation: transactions are enriched with 12 categories and 90 subcategories.
- Merchant Identification: identifies any merchant associated with a transaction and returns its name and logo.
- Regular Transactions: identifies whether a transaction reoccurs over a weekly, monthly, or quarterly period, including (but not limited to) Direct Debits, Standing Orders, regular credit card subscriptions, and regular transfers.

Refresh an Existing Account Connection

The refresh endpoint pulls the latest data from your customer's connected account(s). Without the use of this endpoint, only the transactions that were pulled at the date/time the account was initially connected would be available via the Retrieve OB Data endpoints.

To initiate a refresh for a customer’s accounts, use the POST /v1/open-banking/refresh endpoint (here) with the name of the provider in the body e.g. Barclays. You may also specify the timeframe of the transactions you would like to retrieve using from and to both followed by the date and time of each parameter; in the format 2019-01-01T00:00:00+00:00. If you do not specify a timeframe, transactions will automatically be retrieved, from seven days prior to the date of the most recent transaction within an account (this is to account for any changes in the account information that the provider may have made), and to today's date and time.

You will be provided with a task_id within a successful response which can be used to poll for the status of the refresh task.

{
    "operation_id": "open_banking_provider_refresh_post",
    "data": {
        "task_id": "0169b8b6-69e0-4d85-8e3a-c7aa275eed02"
    },
    "metadata": {
        "next_url": "/v1/open-banking/refresh/0169b8b6-69e0-4d85-8e3a-c7aa275eed02",
        "next_url_delay": 50
    }
}

To see the status of an account refresh use the GET /v1/open-banking/refresh/{task_id} endpoint (here) followed with the task_id. The status will show as Pending, Completed or Failed. If the status is Pending please wait for 10s before retrying (unless it’s time-sensitive, in which case try every 5s). If pending persists, then get in touch with Bud’s Support Desk. Once completed, the data is ready to be collected via the Retrieve Financial Data endpoints. See the payload below for an example of a successful account refresh task.

This payload contains a number of useful fields which will inform your next step. If 'reconnect_required': true then the consent has either expired or been revoked. This means we will no longer be able to fetch new transactions or the balance. In this case, you should prompt your customer to reauthenticate their consent.

📘
The 'has_new_transactions' field will tell you whether any new transactions have been pulled from the provider as part of the refresh. Only if the value is set to true should you then hit our Insight APIs.

{
    "operation_id": "open_banking_provider_refresh_get",
    "data": {
        "bank_name": "Capital_One",
        "provider": "Capital_One",
        "reconnect_required": false,
        "step": 2,
        "text": "Success"
    },
    "metadata": {
        "status": "Completed",
        "has_new_transactions":true
    }
}

If the refresh task has failed you will need to understand why before determining your next step. The reason for the failure will be documented in the "result" field. Please find an example response below.

{
   "operation_id":"open_banking_refresh_get",
   "data":{
      "provider":"Capital_One",
      "reconnect_required":true,
      "result":"connection_revoked",
      "status":"Failed",
      "step":4,
      "task_id":"360e5821-4f18-4077-83f4-c9a7c1768bea",
      "text":"Completed"
   },
   "metadata":{
      "status":"Failed"
   }
}

Please note that clients will also receive a callback on the successful completion of a refresh task. The request payload of the callback from a successful refresh task is as follows:

{  
  "data": {  
    "task_id": "030c78b0-617c-4649-9319-e07569362a14",  
    "task_type": "refresh",  
    "customer_id": "82a90a04-4bdf-446a-932e-fb559ea99c29",  
    "status": "Completed",  
    "result": "success",
    "has_new_transactions": "true",
    "reconnect_required": "false",
    "provider": "Capital_One"
  }  
}

Re-consent

A customer's consent will only ever last for a maximum of 90 days. This means that 90 days after the customer created the initial consent Bud will no longer be able to refresh the account information and the reconnect_required field within the response of a given refresh task status will be set to true.

If you require your customer to consent for a period of longer than 90 days you can prompt your customer to extend their consent by 90 days by calling the Open Banking Authorisation Gateway URL endpoint whilst specifying "reconfirm_consent": true, and "reconfirm_consent_redirect": true.

If the customer re-confirms their consent within 90 days they will only need to reconfirm with Bud, however, if it is beyond the initial 90 days they will need to go through strong customer authentication with their bank similar to the initial connection.

📘
Bud recommends that you store the datetime at which customers provide their initial consent against a given provider. This will allow you to pre-empt when a customer's consent for a given provider is due to expire.

Remove customer consent

If your customer no longer would like to provide access to their account information through the Bud API, it is possible to revoke their consent so that their account information will no longer be accessible by Bud.

To remove your customers consent, start with Initiate Revoke Consent endpoint to perform the task of revoking consent then move to Retrieve Revoke Consent Status to check if it has been completed as outlined below.

CallPOST/v1/open-banking/account-access-consent/revoke endpoint (here) with the customer_id in the request header and name of the provider of the account the customer would like to be removed in the request body. A task_id will be returned as showing in the example below:

{
  "operation_id": "open_banking_provider_revoke_post",
  "data": {
  	"task_id": "01b06f03-46e1-4a0a-91b4-3502aff12774"
  },
  "metadata": {
  	"next_url": "/v1/open-banking/account-access-consent/revoke/01b06f03-46e1-4a0a-91b4-3502aff12774",
  	"next_url_delay": 1000
  }
}

Use the task_id in the following GET /v1/open-banking/account-access-consent/revoke/{task_id} (here) to check the status of the response. Status response can be failed, pending and completed.
1. If the endpoint returns Failed repeatedly; get in touch with support;
2. if Pending, wait a moment and retry; and
3. if Completed, revoking consent for your customer has been successful. An example of a successful response is provided below:

{
  "operation_id": "open_banking_provider_revoke_get",
  "data": {},
  "metadata": {
    "status": "Completed",
    "next_url": "/v1/open-banking/account-access-consent/revoke/01b06f03-46e1-4a0a-91b4-3502aff12774",
    "next_url_delay": 1000
  }
}

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.

View Providers & Check Maintenance Windows

📘What is a maintenance window?

Configure my Callback URL(s)

❗️

Callback Security

Callback URL vs Redirect URL

Connect Account(s) via Bud Connect

❗️

📘

❗️

Fetch Account Information

Refresh an Existing Account Connection

📘

Re-consent

📘

Remove customer consent

📘
What is a maintenance window?