Account
Bank account with balance and metadata.
Property names follow Berlin Group PSD2 accountDetails where they
overlap (iban, bban, bic, maskedPan, product, status,
usage), so servers fronting a PSD2 backend can map fields directly.
Servers SHOULD populate at least one of accountNumber, iban,
bban, or maskedPan.
Properties
| Field | Type | Required | Description |
|---|---|---|---|
accountNumber | string | ✓ | Display-friendly account number in the locally familiar format. For European accounts this is typically the IBAN; otherwise the domestic account number. Use the typed identifier fields (iban, bban, maskedPan) when you need to parse or route on it. Examples: "1234-56-789012", "GB29NWBK60161331926819", "0133-26-007890". |
accountType | AccountType | null | Type of account. Default: null. | |
availableBalance | number | null | Funds available to spend right now in currency, after pending authorisations and including any overdraftLimit headroom. Aligns with the PSD2 interimAvailable balance type. Default: null. | |
balance | number | ✓ | Current booked balance in currency. For credit accounts a negative value indicates an outstanding balance owed. |
balanceUpdatedAt | string | null | ISO 8601 timestamp at which balance and availableBalance were last refreshed by the bank. Default: null. | |
balances | array<Balance> | null | Typed balance entries when the bank exposes more than just the booked and available scalars (ClosingBooked, Expected, InterimAvailable, ForwardAvailable, NonInvoiced). When populated, the top-level balance and availableBalance scalars are derived shortcuts for the most-recent ClosingBooked and InterimAvailable entries; servers MUST keep them consistent. Servers without typed balance support SHOULD omit this field and emit only the scalars. Default: null. | |
bban | string | null | Basic Bank Account Number, the domestic identifier used in countries (or for products) without an IBAN. Default: null. Examples: "BARC12345612345678", "0133-26-007890". | |
bic | string | null | BIC / SWIFT code of the holding bank (ISO 9362). Default: null. Examples: "NWBKGB2L", "DEUTDEFF". | |
currency | string | ✓ | ISO 4217 currency code of the account. For multi-currency accounts (per PSD2 convention) use XXX. Examples: "USD", "EUR", "ISK", "GBP", "XXX". Pattern: ^[A-Z]{3}$. |
iban | string | null | IBAN (ISO 13616), when the account has one. Default: null. Examples: "GB29NWBK60161331926819", "DE89370400440532013000". | |
id | string | ✓ | Unique account identifier (server-scoped) |
isDefaultAccount | boolean | null | Whether this is the user's default account for new transfers. At most one account per response SHOULD have this set to true. Default: null. | |
isWithdrawalAccount | boolean | null | Whether this account can be used as the source of an outgoing transfer or withdrawal. Default: null. | |
maskedPan | string | null | Masked Primary Account Number for card accounts. The middle digits MUST be obscured. Default: null. Examples: "411111xxxxxx1111", "****-****-****-1234". | |
minimumPaymentDue | number | null | Credit accounts only. Minimum payment required by paymentDueDate to keep the account current and avoid late fees, in currency. Servers MUST omit on non-credit accounts. Default: null. | |
name | string | null | Human-readable account name set by the bank or the user. Default: null. Examples: "Main Checking", "Emergency Fund", "Visa Credit Card". | |
openedDate | string | null | Date the account was opened, ISO 8601 (YYYY-MM-DD). Default: null. | |
overdraftLimit | number | null | Approved overdraft on a current/savings account or credit limit on a credit/card account, in currency. 0 (or omitted) means no extra headroom beyond balance. Default: null. | |
ownerName | string | null | Primary account holder's name as the bank holds it. For joint accounts, servers MAY join multiple names with , . Default: null. Examples: "Jane Doe", "Jane Doe & John Doe", "Acme Corp". | |
paymentDueDate | string | null | Credit accounts only. ISO 8601 date by which minimumPaymentDue must be paid. Servers MUST omit on non-credit accounts. Default: null. | |
product | string | null | Bank's marketing name for the account product, per PSD2 product. Free-form and proprietary to the issuer. Default: null. Examples: "Premium Checking", "Visa Signature", "Easy Saver". | |
statementBalance | number | null | Credit accounts only. Total billed on the most recent closed statement, in currency. Pay this in full by paymentDueDate to avoid interest charges. Servers MUST omit on non-credit accounts. Default: null. | |
statementClosingDate | string | null | Credit accounts only. ISO 8601 date the current billing cycle closes and the next statement is generated. Optional even on credit accounts; servers MUST omit on non-credit accounts. Default: null. | |
status | AccountStatus | null | Lifecycle status. If omitted, clients SHOULD treat the account as Enabled. Default: null. | |
usage | AccountUsage | null | Whether this is a personal or business account. Default: null. |
balances[] — Balance
One typed balance entry on an account. Profile of: Berlin Group PSD2 balances array element.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | ✓ | Balance amount in currency. |
asOf | string | null | ISO 8601 timestamp when this balance was last refreshed. Default: null. | |
currency | string | ✓ | ISO 4217 currency code. Pattern: ^[A-Z]{3}$. |
type | BalanceType | ✓ | Balance type. |
Raw JSON Schema
{
"$defs": {
"AccountStatus": {
"description": "Lifecycle status of an account, per Berlin Group PSD2 `accountStatus`.",
"enum": [
"Enabled",
"Blocked",
"Deleted"
],
"title": "AccountStatus",
"type": "string"
},
"AccountType": {
"description": "Type of bank account.\n\nAligned with the ISO 20022 ExternalCashAccountType1Code values exposed\nvia the Berlin Group PSD2 `cashAccountType`, collapsed to the buckets\nthat map cleanly across regions and reflect distinctions a user would\nactually ask about:\n\n - `Current` - day-to-day transaction account (ISO 20022 CACC).\n Debit cards and stored-value / prepaid cards live\n here too: `maskedPan` flags an attached card and the\n balance/availableBalance pair answers \"can I use it?\"\n - `Savings` - interest-bearing savings (ISO 20022 SVGS)\n - `Credit` - revolving credit / credit card account; carries the\n statement-cycle fields below (`statementBalance`,\n `minimumPaymentDue`, `paymentDueDate`, ...).\n - `Loan` - amortizing loan or mortgage (ISO 20022 LOAN)\n - `Other` - anything else (escrow, brokerage, etc.)",
"enum": [
"Current",
"Credit",
"Savings",
"Loan",
"Other"
],
"title": "AccountType",
"type": "string"
},
"AccountUsage": {
"description": "How the account is used, per Berlin Group PSD2 `usage`.\n\n`Private` corresponds to PSD2 `PRIV` (personal); `Business` to `ORGA`\n(professional / organisation).",
"enum": [
"Private",
"Business"
],
"title": "AccountUsage",
"type": "string"
},
"Balance": {
"description": "One typed balance entry on an account.\n\nProfile of: Berlin Group PSD2 `balances` array element.",
"properties": {
"amount": {
"description": "Balance amount in `currency`.",
"title": "Amount",
"type": "number"
},
"asOf": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp when this balance was last refreshed.",
"title": "Asof"
},
"currency": {
"description": "ISO 4217 currency code.",
"pattern": "^[A-Z]{3}$",
"title": "Currency",
"type": "string"
},
"type": {
"$ref": "#/$defs/BalanceType",
"description": "Balance type."
}
},
"required": [
"type",
"amount",
"currency"
],
"title": "Balance",
"type": "object"
},
"BalanceType": {
"description": "Type of balance per Berlin Group PSD2 `balanceType`.",
"enum": [
"ClosingBooked",
"Expected",
"InterimAvailable",
"ForwardAvailable",
"NonInvoiced"
],
"title": "BalanceType",
"type": "string"
}
},
"description": "Bank account with balance and metadata.\n\nProperty names follow Berlin Group PSD2 `accountDetails` where they\noverlap (`iban`, `bban`, `bic`, `maskedPan`, `product`, `status`,\n`usage`), so servers fronting a PSD2 backend can map fields directly.\nServers SHOULD populate at least one of `accountNumber`, `iban`,\n`bban`, or `maskedPan`.",
"properties": {
"accountNumber": {
"description": "Display-friendly account number in the locally familiar format. For European accounts this is typically the IBAN; otherwise the domestic account number. Use the typed identifier fields (`iban`, `bban`, `maskedPan`) when you need to parse or route on it.",
"examples": [
"1234-56-789012",
"GB29NWBK60161331926819",
"0133-26-007890"
],
"title": "Accountnumber",
"type": "string"
},
"accountType": {
"anyOf": [
{
"$ref": "#/$defs/AccountType"
},
{
"type": "null"
}
],
"default": null,
"description": "Type of account."
},
"availableBalance": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Funds available to spend right now in `currency`, after pending authorisations and including any `overdraftLimit` headroom. Aligns with the PSD2 `interimAvailable` balance type.",
"title": "Availablebalance"
},
"balance": {
"description": "Current booked balance in `currency`. For credit accounts a negative value indicates an outstanding balance owed.",
"title": "Balance",
"type": "number"
},
"balanceUpdatedAt": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp at which `balance` and `availableBalance` were last refreshed by the bank.",
"title": "Balanceupdatedat"
},
"balances": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/Balance"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed balance entries when the bank exposes more than just the booked and available scalars (`ClosingBooked`, `Expected`, `InterimAvailable`, `ForwardAvailable`, `NonInvoiced`). When populated, the top-level `balance` and `availableBalance` scalars are derived shortcuts for the most-recent `ClosingBooked` and `InterimAvailable` entries; servers MUST keep them consistent. Servers without typed balance support SHOULD omit this field and emit only the scalars.",
"title": "Balances"
},
"bban": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Basic Bank Account Number, the domestic identifier used in countries (or for products) without an IBAN.",
"examples": [
"BARC12345612345678",
"0133-26-007890"
],
"title": "Bban"
},
"bic": {
"anyOf": [
{
"pattern": "^[A-Z]{6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3})?$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "BIC / SWIFT code of the holding bank (ISO 9362).",
"examples": [
"NWBKGB2L",
"DEUTDEFF"
],
"title": "Bic"
},
"currency": {
"description": "ISO 4217 currency code of the account. For multi-currency accounts (per PSD2 convention) use `XXX`.",
"examples": [
"USD",
"EUR",
"ISK",
"GBP",
"XXX"
],
"pattern": "^[A-Z]{3}$",
"title": "Currency",
"type": "string"
},
"iban": {
"anyOf": [
{
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "IBAN (ISO 13616), when the account has one.",
"examples": [
"GB29NWBK60161331926819",
"DE89370400440532013000"
],
"title": "Iban"
},
"id": {
"description": "Unique account identifier (server-scoped)",
"title": "Id",
"type": "string"
},
"isDefaultAccount": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether this is the user's default account for new transfers. At most one account per response SHOULD have this set to true.",
"title": "Isdefaultaccount"
},
"isWithdrawalAccount": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether this account can be used as the source of an outgoing transfer or withdrawal.",
"title": "Iswithdrawalaccount"
},
"maskedPan": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Masked Primary Account Number for card accounts. The middle digits MUST be obscured.",
"examples": [
"411111xxxxxx1111",
"****-****-****-1234"
],
"title": "Maskedpan"
},
"minimumPaymentDue": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Credit accounts only. Minimum payment required by `paymentDueDate` to keep the account current and avoid late fees, in `currency`. Servers MUST omit on non-credit accounts.",
"title": "Minimumpaymentdue"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Human-readable account name set by the bank or the user.",
"examples": [
"Main Checking",
"Emergency Fund",
"Visa Credit Card"
],
"title": "Name"
},
"openedDate": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Date the account was opened, ISO 8601 (YYYY-MM-DD).",
"title": "Openeddate"
},
"overdraftLimit": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Approved overdraft on a current/savings account or credit limit on a credit/card account, in `currency`. `0` (or omitted) means no extra headroom beyond `balance`.",
"title": "Overdraftlimit"
},
"ownerName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Primary account holder's name as the bank holds it. For joint accounts, servers MAY join multiple names with `, `.",
"examples": [
"Jane Doe",
"Jane Doe & John Doe",
"Acme Corp"
],
"title": "Ownername"
},
"paymentDueDate": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Credit accounts only. ISO 8601 date by which `minimumPaymentDue` must be paid. Servers MUST omit on non-credit accounts.",
"title": "Paymentduedate"
},
"product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Bank's marketing name for the account product, per PSD2 `product`. Free-form and proprietary to the issuer.",
"examples": [
"Premium Checking",
"Visa Signature",
"Easy Saver"
],
"title": "Product"
},
"statementBalance": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Credit accounts only. Total billed on the most recent closed statement, in `currency`. Pay this in full by `paymentDueDate` to avoid interest charges. Servers MUST omit on non-credit accounts.",
"title": "Statementbalance"
},
"statementClosingDate": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Credit accounts only. ISO 8601 date the current billing cycle closes and the next statement is generated. Optional even on credit accounts; servers MUST omit on non-credit accounts.",
"title": "Statementclosingdate"
},
"status": {
"anyOf": [
{
"$ref": "#/$defs/AccountStatus"
},
{
"type": "null"
}
],
"default": null,
"description": "Lifecycle status. If omitted, clients SHOULD treat the account as `Enabled`."
},
"usage": {
"anyOf": [
{
"$ref": "#/$defs/AccountUsage"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether this is a personal or business account."
}
},
"required": [
"id",
"accountNumber",
"currency",
"balance"
],
"title": "Account",
"type": "object"
}