Bud Hosted Refreshes

Firstly, let's explain the difference between a background refresh and a customer initiated refresh.

Background Refresh - When you as the client initiates the refresh of open banking data for each of your customers. This would be an automated process built within your application to trigger a refresh of your entire customer base data over a certain time period.

Customer Initiated Refresh - Your end user/customer initiates the refresh process. For example, the customer logs in to your App and requests an update of their transactions and balance data.

Hosted Refreshes is Bud's new and innovative way to manage background refreshes which ensures the data retrieved for your customers is always up to date. Letting us take control of your background refreshes will simplify the integration process as it means we handle all the complexity of performing background refreshes across your entire customer base. This is our recommended approach to background refreshes. It also gives us the opportunity to continuously improve the refresh journey for you without you having to make any changes.

Customer initiated refresh requests should still be managed by you when the customer is online and using your application. Please integrate the Initiate Refresh endpoint to perform this task.

📘

Requirement

Hosted Refreshes is only available to clients who are utilising Bud's Hosted Customers feature. For more information about Hosted Customers and how to migrate to this solution, please visit the following page.

Enable Bud Hosted Refreshes

To switch on Bud Hosted Refreshes, please get in touch with us, we’ll enable your configuration to allow our flow to start processing background refreshes for your customers.

Prior to us switching this on in production, please consider whether you need to integrate the Refresh Completed Webhook as discussed in the next section.

Lastly, you will need to disable any background refresh functionality on your side (if applicable).

Set up Refresh Completed Webhook (optional)

The first step to start integrating with our Hosted Refreshes solution is to set up the Refresh Completed webhook.

This event is triggered every time Bud completes a refresh for one of your customers: when this happens we send a webhook notification to a URL of your choice so we can let you know when new data is available for each of your customers.

A full guide on how to set up webhooks can be found here, and more details about the Refresh Completed webhook can be found here and here.

An example of a successful callback:

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

And an example of a failure callback:

{  
  "data": {  
    "task_id": "030cf139-1d28-45f5-9721-7e8bdd55f005",  
    "task_type": "refresh",  
    "customer_id": "82a90a04-4bdf-446a-932e-fb559ea99c29",  
    "status": "Failed",  
    "result": "provider_failure",
    "reconnect_required": true
  }  
}

The complete list of status and result values can be viewed here. The result attribute could also be used to determine if a customer consent needs to be reconfirmed to enable a successful refresh to take place.

Please note, the integration of webhooks is not a mandatory requirement to utilise Bud Hosted Refreshes. However it is the recommended approach if your application requires notification of new transactions being available following a refresh.

📘

Note

Another important thing to take into consideration when using the Refresh Completed webhook is that you’ll receive a new webhook notification from Bud every time a refresh is completed without discriminating between customer initiated refreshes triggered by you or background refreshes initiated by Bud.

More information on the Hosted Refresh process

Bud Hosted Refreshes executes one background refresh per Customer per day.

All accounts connected by a Customer are refreshed at the same time.

If you integrate the Refresh Completed webhook, you will receive a separate webhook notifications for each provider we refresh the connection for. For example, If a Customer connected five bank accounts, three with HSBC and two with Monzo, Bud will refresh all five accounts every day, and will send two webhook notifications to you everyday for that customer (one for Monzo and one for HSBC).

Bud Hosted Refreshes distributes the refreshes for your customer base during the 24 hours.

It sends successes and failures callbacks to the same Webhook URL. The result of the execution is included as an attribute in the request body sent to your configured address.

In the event of a failed refresh, we execute multiple retries with the provider without any action needed from you. We will send a separate callback when the refresh completes with success (and on every failure).

When you receive a successful webhook notification, the transactions fetched from the provider are now enriched by Bud and stored in our system. You can fetch the new data once you receive our request.

Bud Hosted Refreshes takes control of your background refreshes when the customer is not online, therefore any background refreshes triggered by you should be disabled once fully migrated.

You can see when the last refresh process has been successfully completed by checking thelast_synched_at attribute on the Retrieve Customer Consents endpoint.

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