Guides
Postman collections ↗Bud Console ↗

Set up Connect with your own license

Suggest Edits

🚧

For regulated clients only

To use this method of connecting with Bud you must be a licensed AISP. This requires a license from the FCA.

If you have questions please contact us to confirm your status

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 Technical Service Provider (TSP). This means that Bud will be using your license (as a registered AISP) in order to provide an Open Banking Aggregation service to your Customers. This will allow you to use your own interface to connect new account(s).

Before starting

Before starting you’ll need:

  • to have provided your account manager with details requested during onboarding to allow Bud to register your Open Banking License with providers (ie banks);
  • 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 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.

Configuring 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 four different webhooks available in regard to the Open Banking Aggregation flow:

  1. 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”).
  2. 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”)
  3. Open banking refresh v2 completed - those who are just interested in the refresh tasks (i.e. not connect). This will fire when an open banking refresh v2 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”)
  4. Open banking refresh v2 provider completed - those who are just interested in the refresh tasks (i.e. not connect). This will fire when each provider a customer has connected within an open banking refresh v2 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”)

❗️

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

Callback URL set up steps

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 (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).

Steps to connect account(s)

The steps to connect your customers(?) account(s) are as follows:

  1. The first step to allow your customers to connect to a new provider, is to make a request to the Initiate Provider Authorisation URL endpoint. Using the POST /v1/open-banking/authorisation-url endpoint (here), you will need to specify a provider_redirect_url and provider (retrieved from the providers endpoint detailed above, value is provider within each object) within the request payload e.g. {"provider": "Natwest_Sandbox", "provider_redirect_url"="https://thisisbud.com/"}.
    This will initiate the process for generating an authorisation URL with the specified provider. The URL returned in the metadata block under the next_url value can then be queried to retrieve the URL to be presented to the user. The output for this request can be found under the Retrieve Authorisation URL endpoint

❗️

Please note that the returned URL returned by authorisation-url/{task_id} needs to be presented to the user within three hours for all providers. Once this expiration time has been reached, you will need to obtain a new URL for that customer by repeating step 1 above.

  1. Direct your customer to the Providers Authorisation URL provided in the response. (maybe add an example, eg send customer to the URL via web browser)
  2. Having completed the authorisation flow with their provider, your customer will then be redirected back to your specified redirect_url provided to your account manager. The provider will return a number of different query parameters in the URL calling your redirect_url. All these query parameters should be transposed into the body of a request to Submit Authorisation Codes POST v2/open-banking/authorisation-codes endpoint (here). This as a minimum needs to include a code and state value as below.
{  
	"code":"test_code",  
	"state":"360e5821-4f18-4077-83f4-c9a7c1768bea"  
}

Please note this should be submitted for all responses.

  1. On a successful submission, Bud will then start fetching your customers account information from the provider. The result of the task can be retrieved using 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.
  2. Additionally 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": {  
    "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

The following 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 /financial/v3/accounts endpoint (here) 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.

  2. Use GET /financial/v2/transactions endpoint (here) to return the latest transactions for all your customers' connected accounts.

  • You can use the X-to and X-from 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

When you create a hosted customer with Bud and connect an account we will perform a background refresh of your customer's data daily, this ensures that you have up-to-date account and transaction information for your customers, and means that you do not need to implement background refreshing within your application.

In cases where your customer is present and they want to perform an additional refresh, you can do so for a customer’s accounts, using the POST /open-banking/v2/refresh endpoint (here). With no providers value specified in the body all providers a customer has connected will be refreshed. You are able to limit this to specific providers using the providers field. 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.

{
  "data": {
    "sub_tasks": [
      {
        "provider": "Lloyds",
        "task_id": "030dfcae-d333-4601-86ae-573ad0e92408"
      },
      {
        "provider": "Natwest",
        "task_id": "030dd774-6474-4031-8081-171a9023c2dd"
      }
    ],
    "task_id": "030d839a-a043-423f-a327-fe0d479add06"
  },
  "metadata": {
    "next_url": "/open-banking/v2/refresh/030d839a-a043-423f-a327-fe0d479add06",
    "next_url_delay": 500,
    "status": "Pending"
  },
  "operation_id": "v2_open_banking_refresh_post"
}

To see the status of an account refresh use the GET /open-banking/v2/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 for each provider refreshed. 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.

{
  "data": {
    "task_id": "030d4a8c-e3b3-4956-8d86-ce3f450c3522",
    "status": "Completed",
    "result": "success",
    "has_new_transactions": true,
    "sub_tasks": [
      {
        "task_id": "030d1679-2cd9-460b-b88a-2627ffcc4db7",
        "provider": "Natwest",
        "status": "Completed",
        "result": "success",
        "reconnect_required": false,
        "has_new_transactions": true
      },
      {
        "task_id": "030dc828-84a9-4d49-895e-63f7c9d86394",
        "provider": "Lloyds",
        "status": "Completed",
        "result": "success",
        "reconnect_required": false,
        "has_new_transactions": false
      }
    ]
  },
  "metadata": {
    "status": "Completed"
  },
  "operation_id": "v2_open_banking_refresh_get"
}

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.

{
  "data": {
    "task_id": "030d4a8c-e3b3-4956-8d86-ce3f450c3522",
    "status": "Failed",
    "result": "connection_revoked",
    "has_new_transactions": false,
    "sub_tasks": [
      {
        "task_id": "030d1679-2cd9-460b-b88a-2627ffcc4db7",
        "provider": "Natwest",
        "status": "Completed",
        "result": "success",
        "reconnect_required": false,
        "has_new_transactions": false
      },
      {
        "task_id": "030dc828-84a9-4d49-895e-63f7c9d86394",
        "provider": "Lloyds",
        "status": "Failed",
        "result": "connection_revoked",
        "reconnect_required": true,
        "has_new_transactions": false
      }
    ]
  },
  "metadata": {
    "status": "Completed"
  },
  "operation_id": "v2_open_banking_refresh_get"
}

Please note that clients will also receive a number of callbacks on the successful completion of a refresh task if subscribed. The request payload of the callback will depend on the event. The overall event (open_banking.v2.refresh.completed) is as followed:

{
  "customer_id": "49d6a33b-7e3e-4052-96cb-04b82fcbdb2f",
  "event":"open_banking.v2.refresh.completed",
  "has_new_transactions": false,
  "task_id": "030d4a8c-e3b3-4956-8d86-ce3f450c3522",
  "result": "success",
  "status": "Completed",
  "sub_tasks": [
    {
      "account_ids": [
        "d607d0da-fb58-497f-ac51-d70f309be304"
      ],
      "consent_ids": [
        "d2e6af8d-ee4b-47ae-b31b-c29c65d43104"
      ],
      "customer_id": "49d6a33b-7e3e-4052-96cb-04b82fcbdb2f",
      "event": "open_banking.v2.refresh.provider.completed",
      "has_new_transactions": false,
      "provider": "Natwest",
      "reconnect_required": false,
      "result": "success",
      "status": "Completed",
      "task_id": "030d4439-6ed5-480e-943e-827a812a45c5"
    },
    {
      "account_ids": [
        "082f6378-0d6b-4e86-8b2d-4fe9562bdd20",
        "27c633ee-988d-4f08-a149-f86257f8d0d9",
        "2c252bbe-3c46-4986-ab7e-66691e906098",
        "4d283655-524f-416f-ad1f-46ea87a39c72",
        "77a79027-00d5-48f9-9a58-d377029befc7",
        "a58d1702-e170-4184-ab55-d96377bb36d0",
        "bde9f97c-b124-4b68-a53f-c3b4547a36ea",
        "bfc1b2a1-047e-4eb0-93c9-8fea39124fa9",
        "c5814a06-4f6d-4e68-9eaf-4263da8d978b",
        "d558d16a-d746-4d11-bd6a-b038f54db392",
        "f1e2a9be-c870-4980-be27-b2fbf4781c15"
      ],
      "consent_ids": [
        "65f4ea18-47f2-4bb3-97c3-a01755df233f"
      ],
      "customer_id": "49d6a33b-7e3e-4052-96cb-04b82fcbdb2f",
      "event": "open_banking.v2.refresh.provider.completed",
      "has_new_transactions": false,
      "provider": "Lloyds",
      "reconnect_required": false,
      "result": "success",
      "status": "Completed",
      "task_id": "030dabd0-7e5d-4b69-afd8-e747f119b049"
    }
  ]
}

For each provider refreshed a provider callback open_banking.v2.refresh.provider.completed) will also be send as followed:

{
  "account_ids": [
    "082f6378-0d6b-4e86-8b2d-4fe9562bdd20",
    "27c633ee-988d-4f08-a149-f86257f8d0d9",
    "2c252bbe-3c46-4986-ab7e-66691e906098",
    "4d283655-524f-416f-ad1f-46ea87a39c72",
    "77a79027-00d5-48f9-9a58-d377029befc7",
    "a58d1702-e170-4184-ab55-d96377bb36d0",
    "bde9f97c-b124-4b68-a53f-c3b4547a36ea",
    "bfc1b2a1-047e-4eb0-93c9-8fea39124fa9",
    "c5814a06-4f6d-4e68-9eaf-4263da8d978b",
    "d558d16a-d746-4d11-bd6a-b038f54db392",
    "f1e2a9be-c870-4980-be27-b2fbf4781c15"
  ],
  "consent_ids": [
    "65f4ea18-47f2-4bb3-97c3-a01755df233f"
  ],
  "customer_id": "49d6a33b-7e3e-4052-96cb-04b82fcbdb2f",
  "event": "open_banking.v2.refresh.provider.completed",
  "has_new_transactions": false,
  "provider": "Lloyds",
  "reconnect_required": false,
  "result": "success",
  "status": "Completed",
  "task_id": "030dabd0-7e5d-4b69-afd8-e747f119b049"
}

Reconsent

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. At this point, you will have to prompt your customers to reconsent to that provider. This is achieved by simply repeating the connect account calls and allowing the customer to complete the connection process again via your interface.

📘

Note

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.

If the customer’s consent is less than 90 days old and hasn’t been revoked it is possible to reconfirm the consent to extend the consent for a further 90 days. This can be achieved using the Reconfirm Consent endpoint with a request to POST /v1/open-banking/account-access-consents/{consent_id}/reconfirm endpoint here.

Remove customer consent

If your customer no longer consent to providing access to their account information, it is possible to revoke their consent by following the steps below. These steps cover calling the Initiate Revoke Consent endpoint to perform the task of revoking consent then calling the Retrieve Revoke Consent Status endpoint to check if it has been completed.

Remove customer consent steps

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

Updated 2 months ago