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 V2 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 V2 endpoint.
The Account Object
The Account object represents a customer's account. Below is an example JSON representation of an Account object from the NatWest Sandbox. We will use this example to talk through the attributes on an account.
{
"account_id":"d607d0da-fb58-497f-ac51-d70f309be304",
"currency":"GBP",
"holder":{
"name":"Debit Card - Nationwide - Jim",
"relationship":"unknown"
},
"account_name":"Debit Card - Nationwide - Jim",
"account_type":"current_account",
"usage_type":"personal",
"provider":"Natwest_Sandbox",
"identifiers":{
"uk_account_number":"22222126",
"uk_sort_code":"805401"
},
"balances":[
{
"date":"2023-05-17T16:15:37Z",
"amount":{
"value":"15906.27",
"currency":"GBP"
},
"type":"expected",
"credit_debit_indicator":"credit"
},
{
"date":"2023-05-17T16:15:37Z",
"amount":{
"value":"15906.27",
"currency":"GBP"
},
"type":"forward_available",
"credit_debit_indicator":"credit"
}
]
}
Balances and Credit Lines
The Balance Object
A single balance object represents the balance amount for a given balance type on an account.
{
"date": "2023-05-17T16:15:37Z",
"amount": {
"value": "15906.27",
"currency": "GBP"
},
"type": "expected",
"credit_debit_indicator": "credit"
}
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.
Type
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 types and what they represent. 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 |
|---|---|
closing_available | Closing balance of amount of money that is at the disposal of the account owner on the date specified. |
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. |
closing_cleared | Closing balance of amount of money that is cleared on the date specified. |
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. |
forward_available | Forward available balance of money that is at the disposal of the account owner on the date specified. |
information | Balance for informational purposes. |
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. |
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. |
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. |
opening_available | Opening balance of amount of money that is at the disposal of the account owner on the date specified. |
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. |
opening_cleared | Opening balance of amount of money that is cleared on the date specified. |
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. |
At this time, Bud considers only balances of type expected and interim_available to include pending transactions.
Credit Debit Indicator
The credit debit indicator indicates if the given balance type is in debit or credit balance.
The Credit Line Object
A line of credit on an account is represented by a Credit Line object. An account can have multiple lines of credit and these indicate the different ways a user can have debit against an account.
{
"date": "2023-01-12T00:00:00Z",
"type": "credit",
"amount": {
"value": "1000.00",
"currency": "GBP"
}
}
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 when using Open Banking Data, or the date and time specified upon balance ingestion using the Ingest Accounts endpoint.
Type
The table below describes the currently supported 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": [
{
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "100.00",
"currency": "GBP"
},
"type": "interim_booked",
"credit_debit_indicator": "debit"
},
{
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "150.00",
"currency": "GBP"
},
"type": "expected",
"credit_debit_indicator": "debit"
}
],
"credit_lines": [
{
"date": "2023-01-12T00:00:00Z",
"type": "available",
"amount": {
"value": "850.00",
"currency": "GBP"
}
},
{
"date": "2023-01-12T00:00:00Z",
"type": "credit",
"amount": {
"value": "1000.00",
"currency": "GBP"
}
}
]
}
The Balances
This customer has spent £100 on this credit card and has an additional £50 pending.
We know this because there is a balance of type expected with an amount of £150 and a balance of type interim_booked with an amount of £100. From this, we know that there is £50 pending.
These are debit balances as this is a credit card.
The Credit Lines
This account has a credit limit of £1000, and has £850 of that remaining.
We know this because there is a Credit Line of type credit which tells us the credit limit is £1000. There is also a Credit Line of type available, which tells us the remaining credit available on the account is £850.
Current Account
Below is an example of a current account with both Balances and Credit Lines.
{
"balances": [
{
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "100.00",
"currency": "GBP"
},
"type": "interim_booked",
"credit_debit_indicator": "credit"
},
{
"date": "2023-01-12T00:00:00Z",
"amount": {
"value": "50.00",
"currency": "GBP"
},
"type": "expected",
"credit_debit_indicator": "debit"
}
],
"credit_lines": [
{
"date": "2023-01-12T00:00:00Z",
"type": "pre_agreed",
"amount": {
"value": "100.00",
"currency": "GBP"
}
},
{
"date": "2023-01-12T00:00:00Z",
"type": "emergency",
"amount": {
"value": "10.00",
"currency": "GBP"
}
}
]
}
The Balances
This customer has £100 in their current account, which we know from the balance of type interim_booked with the credit indicator set.
When all of the pending transactions have settled, the account balance will be -£50, which we know from the balance of type expected with the debit indicator set. The 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 agreed overdraft of £100, and has £10 emergency overdraft in addition.
Updated 3 months ago