Accounts
Here, we will introduce you to the concept of an Account on the Bud platform. When we talk about an Account at Bud, we are referring to a representation of a customer's connected bank or building society account.
You can use the Retrieve Accounts V3 endpoint to retrieve a list of all accounts Bud has on record for a customer. Or if you only want to retrieve a single account by ID, you can use the Retrieve Account By ID V3 endpoint.
The Account Object
The Account object represents a customer's account. Below is an example JSON representation of an Account object that we will use to talk through the attributes of an account.
{
"operation_id": "financial_v3_accounts",
"data": [
{
"account_id": "RxsYshVGded4JeilkXgWKdXA",
"currency": "GBP",
"holders": [
{
"name": "David Smith",
"relationship": "unknown"
}
],
"account_name": "My Current Account",
"account_type": "current_account",
"usage_type": "personal",
"provider": "BankOfBud",
"identifiers": {
"uk_sort_code": "126432",
"uk_account_number": "31510604"
},
"balances": {
"booked": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "3552.61",
"currency": "GBP"
},
"credit_debit_indicator": "credit"
},
"pending": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "3552.61",
"currency": "GBP"
},
"credit_debit_indicator": "credit"
}
},
"credit_lines": {
"limit": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "1000.00",
"currency": "GBP"
}
}
}
}
],
"metadata": {
"parameters": {
"currencies": [
"GBP"
]
},
"results": 1
}
}
Balances and Credit Lines
The Balance Object
The balance object represents the balance for an account. Balances at Bud are normalised into either a booked or pending balance, where possible we will show both balances but a single balance may be returned depending on the balance types that we receive at the point of ingestion.
...
"balances": {
"booked": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "3550.00",
"currency": "GBP"
},
"credit_debit_indicator": "debit"
},
"pending": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "3600.00",
"currency": "GBP"
},
"credit_debit_indicator": "debit"
}
},
"credit_lines": {
"limit": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "5000.00",
"currency": "GBP"
}
}
}
...
If you would like to view all balance types that Bud has stored you can do so by setting the query parameter include_all_balances to true.
Date
The date on the balance object indicates at what date and time the balance was taken from. This is typically the date and time that the customer's account was refreshed when using Open Banking data, or the date and time specified upon account ingestion using the Ingest Accounts endpoint.
Amount
The amount is the balance value and currency represented by the given balance object.
The value of the amount is purely the balance of the account and does not represent any kind of credit limit or overdraft.
If ingested using the Ingest Accounts endpoint
If the account was ingested using the Ingest Accounts endpoint, if any credit lines have been ingested with the flag
includedastrue, the credit line amount is deducted from the ingested balance amounts so that the balances are more indicative of the true balance state of the account.
Balance Types
The type of balance generally indicates when the balance data was taken, and if it includes pending transactions or not.
The table below describes the currently supported raw balance types, what they represent and whether they will be normalised as a booked or pending balance. Many of the balance types correspond to those in the ISO 20022 standard. Please note this table is not exhaustive and may be extended in the future without notice.
| Type | Description | Normalised |
|---|---|---|
closing_available | Closing balance of amount of money that is at the disposal of the account owner on the date specified. | pending |
closing_booked | Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. | booked |
closing_cleared | Closing balance of amount of money that is cleared on the date specified. | booked |
expected | Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. | pending |
forward_available | Forward available balance of money that is at the disposal of the account owner on the date specified. | pending |
information | Balance for informational purposes. | pending |
interim_available | Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. | pending |
interim_booked | Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. | booked |
interim_cleared | Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. | booked |
opening_available | Opening balance of amount of money that is at the disposal of the account owner on the date specified. | pending |
opening_booked | Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. | booked |
opening_cleared | Opening balance of amount of money that is cleared on the date specified. | booked |
previously_closed_booked | Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. | booked |
Calculating the balance of Monzo Pots
Please note, Monzo uses the
informationbalance type to return the total amount in a customers account including pots. By subtracting theinterim_availableamount from theinformationamount you can calculate the total amount a customer holds across their pots.
Credit Debit Indicator
The credit debit indicator indicates if the given balance is in debit or credit balance.
The Credit Line Object
Similar to balances, credit_lines are also normalised at Bud into a limit for the account. In cases of a debit account, this will represent the overdraft and for credit cards, this will represent the credit limit.
The normalised limit amount will always reflect the total limit for the account, for debit accounts this is the total amount of the overdraft and for credit accounts this is the total limit (not taking into consideration any existing balance on the account).
...
"balances": {
"booked": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "100.00",
"currency": "GBP"
},
"credit_debit_indicator": "credit"
},
"pending": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "50.00",
"currency": "GBP"
},
"credit_debit_indicator": "debit"
}
},
"credit_lines": {
"limit": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "100.00",
"currency": "GBP"
}
}
}
...
If you would like to view all credit_lines types that Bud has stored you can do so by setting the query parameter include_all_balances to true.
Date
The date on the Credit Line object indicates at what date and time the Credit Line was taken from. This is typically the date and time that the customer's account was refreshed, or the date and time specified upon balance ingestion using the Ingest Accounts endpoint.
Credit Line Types
The table below describes the currently supported raw credit line types and what they represent. Please note this is not exhaustive and may be extended in the future without notice.
| Type | Description |
|---|---|
| available | Indicates the amount of credit that is available to spend on the account. This type usually takes into account the current balance of the account. This field is often present when the account is a form of credit account such as accounts of the type credit_card. |
| credit | Indicates the amount of credit on the account. This type does not usually take into account the current balance of the account. This field is often present when the account is a form of credit account, such as accounts of type credit_card. |
| emergency | This is usually a type of overdraft on an account for emergency use when other overdraft limits have already been met. |
| pre_agreed | This is usually a type of overdraft on an account that has been agreed to by both the customer and the bank. |
| temporary | This is usually a type of overdraft that is extended for a temporary time. |
Amount
The amount is the Credit Line value and currency represented by the given Credit Line object.
The value of the amount is the amount of credit being provided to the customer's bank account for the given type of credit.
Examples
Credit Card
Below is an example of a Credit Card account with both Balances and Credit Lines.
...
"balances": {
"booked": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "3550.00",
"currency": "GBP"
},
"credit_debit_indicator": "debit"
},
"pending": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "3600.00",
"currency": "GBP"
},
"credit_debit_indicator": "debit"
}
},
"credit_lines": {
"limit": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "5000.00",
"currency": "GBP"
}
}
}
...
The Balances
This customer has spent £3550 on this credit card and has an additional £50 pending.
We know this because there is a balance of type pending with an amount of £50 higher than the booked balance.
These are debit balances as this is a credit card.
The Credit Lines
This account has a total credit limit of £5000, we know this because there is a Credit Line that tells us the credit limit is £5000. A remaining limit can be calculated by subtracting the pending balance from the limit.
Current Account
Below is an example of a current account with both Balances and Credit Lines.
...
"balances": {
"booked": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "100.00",
"currency": "GBP"
},
"credit_debit_indicator": "credit"
},
"pending": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "50.00",
"currency": "GBP"
},
"credit_debit_indicator": "debit"
}
},
"credit_lines": {
"limit": {
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "100.00",
"currency": "GBP"
}
}
}
...
The Balances
This customer has £100 in their current account, which we know from the booked balance with the credit indicator set.
When all of the pending transactions have settled, the account balance will be -£50, which we know from the pending balance with the debit indicator set. This customer will be utilising their overdraft.
We can deduce that there are pending transactions totalling £150 on the account.
The Credit Lines
This account has an overdraft of £100, which we know from the limitset to 100.00.
Updated 8 days ago