Guides and tutorials

Integrate Bud's Open Banking aggregation TPP flow

Below we’ll provide you with a step-by-step guide to help you integrate Bud’s Open Banking Aggregation service when using Bud as a Third Party Provider (TPP). 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 a

  • valid customer_id and customer_secret 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 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/Monzo@3x.png",
"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

Clients are required to configure their Callback URL in order to receive event notifications regarding the status of different tasks. In terms of the Open Banking Aggregation flow, Bud will use your Callback URL to send requests detailing the status of different account connection and refresh tasks.

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 Open Banking Sync Complete

  • Input your chosen URL into the text space provided.

The Callback URL specified will be used to notify you when Bud has completed fetching the customer’s account information from the relevant ASPSP, after (i) successful customer authorisation, or (ii) a successful refresh task. At this point, the customer’s account information will be ready to collect via the Retrieve OB Data endpoints.

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

 

Difference between the Callback URL and 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

  1. 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 /v1/open-banking/authorisation-gateway-url endpoint, 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 except for AMEX, where the authorisation expiration time is set to just 10 minutes. Once this expiration time has been reached, you will need to obtain a new authorisation-gateway-url for that customer.

  1. Direct your customer to the Bud Connect Authorisation Gateway URL provided in the response.

    • Your customer will be shown the customer consent screen where they will agree to Bud’s data sharing terms and conditions.

    • They can then select their chosen provider from the list (below is an example of the providers available via Bud’s sandbox environment).

    • 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 providers relevant application (i.e. app-to-app), your customer will need to enter their banking credentials and complete the authentication process with their provider.

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

  1. On successful customer authorisation, Bud will then start fetching your customers account information from the provider. The result of this task will be pushed to your configured Callback URL. An example request payload within a callback of a successful connection task is follows:

{
"data": {
"event": "open-banking.sync.success",
"task_type": "connect",
"customer_id": "cb43172f-418a-46e9-b8ab-508654fbc7e3",
"task_id": "360e5821-4f18-4077-83f4-c9a7c1768bea",
}
}

 

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 List Accounts and List 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.

  1. Use the GET /v1/open-banking/accounts endpoint to return all of your customers’ connected accounts in the response. You can also specify the account_id in the request headers to return the data for a specific bank account. The results field found within the metadata object shows the number of accounts returned in the response body.

  1. Use GET /v1/open-banking/transactions to return the latest transactions for all your customers' connected accounts.

  • You can use the X-to and X-from parameters to specify a timeframe, without using a timeframe by default the endpoint will return the last three months.

  • You can use the account_id of your customers account in order to return transactions for a specific account.

  • The transaction information is returned with various enrichments that have applied to the data, which include:

    • 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 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 GET /v1/open-banking/refresh/{task_id} followed with the task_id. The status will show as Pending or Completed, if Pending wait a short time and retry. If pending persists, then get in touch with Bud’s helpdesk. Once completed, the data is ready to be collected via the Retrieve Open Banking Data endpoints. See the payload below for an example of a successful account refresh task.

{
"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"
}
}


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": {
"event": "open-banking.sync.success",
"task_type": "refresh",
"customer_id": "cb43172f-418a-46e9-b8ab-508654fbc7e3",
"task_id": "360e5821-4f18-4077-83f4-c9a7c1768bea",
}
}

 

Reconsent

A customer's consent will only ever last for a maximum of 90 days. This means that 90 days after a customer created an initial connection to a given provider, their consent for that provider will expire, and Bud will be unable to refresh the customer's account information for that provider. In this scenario, the reconnect_required field within the response of a given refresh task status will be set to true. At this point, you will have to prompt your customers to reconsent to that provider. This is achieved by simply calling the Open Banking Authorisation Gateway URL endpoint and allowing the customer to complete the connection process again via Bud Connect.

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.

  1. POST /v1/open-banking/account-access-consent/revoke 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
}
}

  1. Use the task_id in the following GET /v1/open-banking/account-access-consent/revoke/{task_id} to check the status of the response. Status' within the response can be failed, pending and completed. If the endpoint returns Failed repeatedly; get in touch with the help desk, if Pending, wait a moment and retry and 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
}
}

Looking for more?

Get in touch with one of the team

Get started

Market coverage

All of our connections for account aggregation and payments

Get started

API Docs

Take a look at the resources available for our APIs.

API Docs