Refreshing customer accounts

📘

The majority of Bud's clients create hosted customers who we perform background refreshes for. You can learn more about the benefits of hosted customers and hosted refreshes here.

If you're not creating hosted customers and intend to implement background refreshes within your application please continue reading.

The ability to refresh customers' data is an important part of Open Banking (OB) and one of the key advantages over other sources of financial data like credit reference agencies (CRA). With OB, clients are able to refresh a customer's account data in the background daily and more frequently if the customer requests.

When initiating refreshes it’s important to consider the concurrency of requests. In order to control the use of their APIs, banks often set rate limits on the number of calls that can be made at once. If Bud exceeds these rate limits we will receive a 429 response from the banks as detailed by the Open Banking Specification. Since the limit is set by the bank, it is unfortunately out of Bud’s control, furthermore, each bank has its own logic as to how it applies rate limits and varies widely, because of this it is important to spread out your refreshes throughout the day.

A client who is trying to refresh all accounts in bulk, like below, is likely to experience a higher rate of request failures than a client who spreads refreshes over the course of a day.

Refresh recommendations

Below we have documented two approaches you can take in order to spread these requests.

Queuing refreshes

One approach you can take is to queue customer refreshes and fix the number of concurrent refreshes. You should start with the minimum concurrency necessary to refresh your user base during a one-day window and as your user base increases, you can increase your concurrency as appropriate to ensure all accounts can be refreshed at least once a day. Below are examples of how many users per day would be refreshed assuming a constant concurrency:

Random allocation

Alternatively, you can allocate a random offset for each of your accounts on the time that they should be refreshed, the fact that the allocation is random will ensure that refreshes are spaced equally and will help to avoid hitting bank rate limits.

By following one of these two methods you will be able to lower the upper bound of refreshes that are happening concurrently and therefore reduce the number of refresh failures that you experience.

If you would like more information on how to perform an account refresh you can find more information below.

To initiate a refresh for a customer’s accounts, use the POST open-banking/v2/refresh endpoint (here) If you only wise to refresh a subset of a customers accounts please specify a list of providers if no list is specified then all connections are refreshed. 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. The minimum value for from is 90 days before today's date and time. 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 GET open-banking/v2/refresh/{task_id} (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 helpdesk. 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"
}

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