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. |
| 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. |
| 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. |
| 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 within your integration through the use of the available query parameters on the retrieve transactions endpoint. For example use the date_from and date_to parameters to only retrieve the transactions you want. Ensure to integrate pagination capability so that you retrieve all available transactions through the use of the page_token parameter. |
| 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. Background refreshes should be carried out using 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 12 days ago