Setup Bud Connect

Below, we provide a step-by-step guide to help you integrate Bud Connect to allow your customers to connect their bank account(s) using the UI provided and hosted by Bud.

Before starting, you’ll need to generate :

• A valid OAuth access token. For further details on how to authenticate to Bud’s APIs, please see this guide.
• A valid customer_id. For further details on how to create a customer, please see this guide.

Connect Account(s) via Bud Connect

1. After completing the above steps, you should then send a request to the Authorization Gateway URL endpoint here. You will need to specify a redirect_url within the request payload which the customer will be redirected to once they have completed the authorization process.
   Please note the URL that we generate is valid for 30 minutes. If the customer doesn't complete the authentication journey with their bank within that time limit, the account connection will result in a failure and a new Authorization Gateway URL will need to be generated.
2. Direct your customer to the Bud Connect Authorization Gateway URL provided in the response.
   • Your customer will then need authenticate with their bank and provide consent to their accounts.
   • Once your customer has logged in to their bank, they will be presented with a consent screen owned and hosted by their bank which provides details about the flow and the data shared.
3. Having completed the authorization flow with their provider, your customer will then be redirected back to Bud, where they will see a success screen and a button to continue their journey back to your application.
4. When the customer is redirected back to your specified redirect_url the status of the authorization task will be shown within the redirect URL (as a path parameter) along with a unique task_id. If ?status=success the customer has been successfully authorized with their chosen provider. If ?status=failed then the authorization step has failed, and the customer will need to retry the authorization with their chosen provider. The task_id parameter can be used to check the status of a connection and is also useful when getting in touch with us to request technical support.
5. 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. 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 setup and configured within our developer console and should be used to check the status of tasks rather than using the Get Status endpoints.
6. When the connection status has been confirmed as successful, it means the customer's data is now enriched and ready to be accessed.

Fetch Account Information

To view the customer's account information, you will need to use the Retrieve Accounts and Retrieve Transactionsendpoints.

As mentioned above please make sure to wait for the connection task to be successfully completed before calling the following endpoints.

1. Use the GET /financial/v2/accounts endpoint (here) to retrieve all of your customers’ connected accounts. The results field found within the metadata object shows the number of accounts returned in the response body.

2. Use the GET /financial/v2/accounts/{account_id} endpoint (here) to retrieve the data for a specific account.

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

Refresh an Existing Account Connection

The initiate refresh endpoint pulls the latest data from your customer's connected account(s). Without the use of this endpoint, only the account balances and transactions that were pulled at the date/time the account was initially connected would be available.

It's important to note that financial data is published by most providers daily over night, so we suggest you execute customer refreshes after 06:00 ET, to make sure you retrieve the latest account balances and transactions published that relate to the previous day.

You can run a maximum of one refresh per customer per day. 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. Please refer to the Bud Hosted Refreshes guide here for more information.

To learn more on how to execute a refresh request, please, refer to the API documentation here.

Consent life

A customer's consent will last for a maximum of 12 months. This means that 12 months 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.

When the consent has expired, the customer will need to go through the connection flow again. Please refer to the Connect Account(s) via Bud Connect section above.

When the Customer consents to share the data again, assuming you have reconnected using the same customer_id, Bud will fetch the new data and append it to the existing list of transactions stored so far without generating duplicates.

Customers are also able to revoke their consents using their online banking application. In addition to this, the bank itself has the right to revoke the consent at any time at their discretion. We strongly recommend integrating with our webhooks as these can alert you to these types of events where the customer may need to reconnect their account.

Remove customer consent

If your customer no longer wants to provide access to their account information through the Bud Platform, it is possible to revoke their consent so that their account information will no longer be accessible by Bud.

Our Bud Connect UI can be configured to allow your customers to manage their given consents. In order to do so, you will need to call the Authorization Gateway URL endpoint here and include in the request body the initial_screen parameter with one of the following values:

• accounts_summary: This will show a list of the names and balances of the accounts that the customer currently has active consents for. At the top right, they will see a menu icon that allows them to be redirected to the "Revoke Consents" screen
• revoke_consent: This will show the "Revoke Consents" screen as first page.

Alternatively, you can design and host your own Revoke Consents flow, and use the Initiate Revoke Consent endpoint to request Bud to remove the customer's given consent.

1. CallPOST/v1/open-banking/account-access-consent/revoke endpoint (here) with the customer_id set in the request header and the name of the provider set in the request body.
   A task_id will be returned in the Revoke Consent response as shown 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
  }
}

2. Use the task_id with the following endpoint GET /v1/open-banking/account-access-consent/revoke/{task_id} (here) to check the status of the Revoke Consent task. The status will be returned as failed, pending or completed.
   1. If the endpoint returns Failed repeatedly; get in touch with support
   2. if Pending, wait a moment and retry
   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
  }
}

❗️

Please note that it is a mandatory requirement to choose and integrate with one of the two options above to allow your customers to revoke their consents.

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