Best Practice Recommendations
Optimise and fine tune your integration with Bud by following these recommendations.
Below we provide some best practice recommendations and things to consider when integrating the Bud API and preparing to move into production.
| Item | Best Practice Recommendation |
|---|---|
| Console and Sandbox Access | Sign up to the Bud developer console and generate a new Project/API key to access our sandbox environment. If other members of your team need access, invite them to join you through the Bud developer console to make sure you share access to the same Projects. |
| Open API, API Docs and Guides. | Review and Download our Open API file. Review the applicable API docs and separate user guides for the endpoints you are integrating to understand how best to use these and to gain a good understanding of the request parameters and response structures as well as any error codes. Can't find what you are looking for, simply click the “Ask AI” button which can be found on all our docs and guides and ask it a question! |
| Postman Collection | Download the latest Postman collection and connect to our sandbox environment using the available test data in our developer console. |
| Auth Token Handling | Auth tokens expire every 60 minutes. Fetch and cache access tokens within your application and before expiry, fetch a new access token. Our recommendation is to fetch a new auth token every 30 mins or in the event that you receive a 401 error. Token expiration is a maximum expiration so things can happen (such as token revocation) that means tokens expire at any point up until then and you don't want to then be unable to call APIs until your next scheduled token fetch. To improve performance avoid generating a new Auth token before every request. |
| Creating Customers | If you are integrating Assess and only require a one time consent from the customer instead of ongoing consent, you should integrate with the Assess API to create customer applications. For all other Bud solutions e.g Engage, you should integrate with the Customers API to create hosted customers on the Bud platform. Only create new customers on the Bud platform when the customer is going to connect/ingest their bank account information. |
| Open Banking Licence | The endpoints that you will need to call for the initial bank account connection will depend on what Open Banking licence you are using. Bud Open Banking Licence (Recommended) This means that you’ll be using Bud’s licence as a registered Account Information Service Provider (AISP) in order to provide an Open Banking Aggregation service to your customers. As a result, you will integrate Bud’s Connect user interface to allow your customers to connect their bank account(s). Client Open Banking Licence Bud will be using your licence as a registered Account Information Service Provider (AISP) in order to provide an Open Banking Aggregation service to your customers. This will allow you to create/use your own interface to allow customers to connect their bank account(s). |
| First Party Ingestion | First Party Ingestion is the term used to describe the process of sending raw transaction and account data to the Bud Platform in order for us to enrich this data. Once the data is in the Bud Platform and enriched, you can then make API calls to your contracted Bud Solution (Assess, Engage). Only integrate First Party Ingestion endpoints if you already have access to your customers raw accounts and transactions data. The standard way to access your customers accounts and transactions data is using the Bud Connect journey which is covered in the row above. Your application should wait until the ingest task for a customer has successfully completed before making any subsequent ingestion requests or calling any other API endpoints such as retrieve accounts, balances or transactions endpoints. |
| Wait for the Bank Account Connection to Complete | Your application should wait until the bank account connection process has successfully completed before calling any other API endpoints such as retrieve accounts, balances or transactions endpoints. We can send your application a webhook notification as soon as the bank account connection process is complete. This will reduce the risk of you receiving partially enriched transactions or account data. |
| Bud Generated URL's | The generated URL that the customer uses to complete the bank account connection journey is valid for 30 minutes. Please ensure to generate the URL right before sharing it with the customer to avoid them navigating to an expired link. If you communicate the generated URL with your customers through long lived messages (emails, notifications), please ensure to have a mechanism to generate the URL when the customer is online and ready to connect their bank account. Please refer to the Creating Customers section above to determine the appropriate method of generating this URL for your customer. |
| Webhooks Integration | We strongly recommend integrating with our webhooks in order to receive up-to-date account and transaction information in addition to event notifications regarding the status of different tasks. Webhooks are set up and configured within our developer console and should be used to check the status of tasks rather than using the Get Status endpoints. |
| Get Status | If you are not using webhooks you should still be checking the status of tasks such as the initial bank account connection and refreshes of data to ensure these are successful before proceeding to call other API endpoints. You should however limit the frequency of polling these Get Status endpoints to 500 ms. Webhooks are the recommended approach to checking the status of tasks. |
| Task Failures | In the event of a failed task such as a failed bank account connection or failed refresh, your integration should handle this failure appropriately to ensure the customer has the opportunity to try again/reconnect. |
| Retrieving Transactions | Optimise retrieving transactions so that you are only requesting new or updated transactions. Once the customer has connected their bank accounts, we recommend retrieving and storing historical transactions as far back as you need. You should integrate pagination capability so that you retrieve all available transactions through the use of the page_token parameter. Subsequent calls to retrieve transactions should then only be typically needed following data refreshes i.e when we send a refresh completed webhook notification saying there are new transactions available ("has_new_transactions": true). Please also make use of the date_from, date_to or updated_after query parameters on this endpoint to only retrieve the transactions you want to display to your customers. |
| Refreshing Data | Customer initiated refreshes should only be executed when the customer is logged in to your application and requests should be rate limited to a maximum of 2 customer initiated refreshes per customer per day. Your application should wait until the refresh task has successfully completed before calling any other API endpoints such as retrieve accounts, balances or transactions endpoints. Clients wishing to perform background refreshes can do so using Bud's Hosted Refreshes. 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. |
| Reconfirm Consents | If you require ongoing access to your customer's bank accounts you will need to allow your customers to reconfirm consent every 90 days or less to ensure the consent remains active. If you are using Bud’s Open Banking licence please use the /authorisation-gateway-url endpoint, setting the following parameter within the request body "initial_screen": "reconfirm_consent".If you are using your own Open Banking licence you can use the /reconfirm endpoint. Please note, a customer must be present and agree to extending their consent before you hit the /reconfirm endpoint. |
| Error Handling | Build in controls to handle errors that can be returned from Bud endpoints. For example if you receive a 401 error from a Bud endpoint, you should try to fetch a new token immediately and then retry. When reporting errors to Bud make sure to include the value of the x-upstream-request-id response header, and the timestamp of the request. |
| Deprecated Endpoints | Always integrate against the latest version of each API endpoint. Migrate away from deprecated endpoints to newer versions when they become available. |
| Future Proofing | Ensure non-breaking/additive changes implemented by Bud do not break your integration. For example if we add a new optional field to an existing endpoint, this should not break your integration. |
Please reach out to your Technical Delivery contact if you have any questions throughout the integration and we will be happy to help.
You can contact us via the chatbot (bottom-right of screen 👉) or via a Technical Support Request.
Updated 8 days ago