prepare-transfer
Prepare a money transfer on any supported rail (SEPA, SEPA Instant, SWIFT, domestic-IS, etc.). Validates the creditor, computes fees / FX / payee verification when applicable, and returns a transferIntentId plus a summary the user confirms. Does NOT execute; pass the intent id to execute-transfer.
Input
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | ✓ | Instructed amount in currency. |
creditor | Party | ✓ | Creditor record. accountIdentifier is required for routing; name is required for display and Confirmation-of-Payee on rails that support it. |
currency | string | ✓ | ISO 4217 currency code of the instructed amount. Examples: "ISK", "EUR", "USD". Pattern: ^[A-Z]{3}$. |
debtor_account_id | string | ✓ | Source Account.id from get-accounts. |
description | string | null | Free-text shown on the counterparty's statement. Falls back to remittance_information.unstructured when both are set. Default: null. | |
end_to_end_id | string | null | Optional client-supplied ISO 20022 cross-rail identifier. Servers MUST generate one when the client omits it; the resolved value is echoed in the response summary. Default: null. | |
idempotency_key | string | null | Optional idempotency key, scoped to this tool. Servers SHOULD return the original prepared-transfer response for repeat calls with the same key within at least 24 hours. Default: null. | |
local_instrument | string | null | Rail-specific instrument code; INST for SEPA Instant, RTGS for SWIFT, etc. Free-form per rail. Default: null. | |
rail | "domestic-IS" | "sepa" | "sepa-instant" | "swift" | ✓ | Settlement rail. Drives validation, fees, and the set of meaningful local_instrument values. |
remittance_information | RemittanceInformation | null | Structured / unstructured remittance information to attach to the transfer. Default: null. | |
requested_execution_date | string | null | ISO 8601 (YYYY-MM-DD) requested execution date. Omit for as-soon-as-possible per the rail. Default: null. |
creditor — Party
Creditor record. accountIdentifier is required for routing; name is required for display and Confirmation-of-Payee on rails that support it.
| Field | Type | Required | Description |
|---|---|---|---|
accountIdentifier | IbanIdentifier | BbanIdentifier | AccountNumberIdentifier | AliasIdentifier | null | Party's account identifier when known. Default: null. | |
bic | string | null | BIC / SWIFT code of the party's bank, ISO 9362. Default: null. Examples: "NWBKGB2L". | |
brandName | string | null | Brand or chain name the party belongs to, when name is a specific outlet of a larger brand. For card transactions this is the merchant's parent brand (e.g. name = "Starbucks Reserve Roastery", brandName = "Starbucks"). Clients MAY use brandName to group transactions by chain while still displaying the specific outlet on each row. Default: null. Examples: "Starbucks", "Bónus". | |
latitude | number | null | Geographic latitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group geoLocation (latitude component). Default: null. Examples: 48.8566, 64.1466. | |
longitude | number | null | Geographic longitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group geoLocation (longitude component). Default: null. Examples: 2.3522, -21.9426. | |
name | string | ✓ | Party's full name or business name. |
nationalId | NationalId | null | Party's national identifier when known. Default: null. | |
postalAddress | PostalAddress | null | Postal address of the party. For card transactions, this is the merchant / card-acceptor address (Open Finance cardAcceptorAddress). Servers SHOULD populate whatever subset they have, typically at least townName and country. Default: null. |
accountIdentifier — type: "iban"
IBAN-routed account, ISO 13616.
| Field | Type | Required | Description |
|---|---|---|---|
iban | string | ✓ | IBAN, ISO 13616. Examples: "GB29NWBK60161331926819", "DE89370400440532013000". Pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$. |
type | string | Discriminator: iban. Default: "iban". |
accountIdentifier — type: "bban"
Domestic Basic Bank Account Number, used in markets without an IBAN.
| Field | Type | Required | Description |
|---|---|---|---|
bban | string | ✓ | Domestic account identifier in the country's native format. Examples: "0133-26-007890". |
country | string | ✓ | ISO 3166-1 alpha-2 country code. Examples: "IS", "GB". Pattern: ^[A-Z]{2}$. |
type | string | Discriminator: bban. Default: "bban". |
accountIdentifier — type: "accountNumber"
Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).
| Field | Type | Required | Description |
|---|---|---|---|
accountNumber | string | ✓ | Account number in the country's native format. |
country | string | ✓ | ISO 3166-1 alpha-2 country code. Examples: "US", "GB". Pattern: ^[A-Z]{2}$. |
routing | string | null | US ABA routing number, when applicable. Default: null. | |
sortCode | string | null | UK sort code, when applicable. Default: null. | |
type | string | Discriminator: accountNumber. Default: "accountNumber". |
accountIdentifier — type: "alias"
Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).
| Field | Type | Required | Description |
|---|---|---|---|
alias | string | ✓ | The alias value as the user knows it. Examples: "alex@upi", "+44-7700-900000". |
aliasType | "email" | "phone" | "vpa" | "pix" | "other" | ✓ | Kind of alias. |
type | string | Discriminator: alias. Default: "alias". |
nationalId — NationalId
Person or business national identifier.
| Field | Type | Required | Description |
|---|---|---|---|
country | string | ✓ | ISO 3166-1 alpha-2 country code. Examples: "IS", "US". Pattern: ^[A-Z]{2}$. |
type | "ssn" | "kennitala" | "cpr" | "personnummer" | "cpf" | "other" | null | Hint for the kind of identifier. bank2ai does not validate the value. Default: null. | |
value | string | ✓ | National identifier value, in the country's native format. Examples: "010190-1234", "123-45-6789". |
postalAddress — PostalAddress
Postal address of a party or card-acceptor merchant. Profile of: ISO 20022 PostalAddress24 (subset). Aligns with the Open Finance / Berlin Group cardAcceptorAddress structure so card transactions can surface where the swipe happened. Servers SHOULD populate whichever subfields the bank exposes and omit the rest; townName and country are the most commonly available and the most useful for LLM context.
| Field | Type | Required | Description |
|---|---|---|---|
addressLine | array<string> | null | Free-form address lines, used when the bank exposes the address as unparsed text. Servers SHOULD prefer the typed fields above and fall back to addressLine only when they cannot decompose the address. Default: null. | |
buildingNumber | string | null | Building number on the street. Default: null. Examples: "12", "12B". | |
country | string | null | ISO 3166-1 alpha-2 country code. Default: null. Examples: "FR", "SE", "IS", "US". | |
countrySubDivision | string | null | State, province, region, or other top-level subdivision. Default: null. Examples: "CA", "Île-de-France". | |
postCode | string | null | Postal / ZIP code. Default: null. Examples: "75001", "SW1A 1AA". | |
streetName | string | null | Street name without the building number. Default: null. Examples: "Rue de Rivoli". | |
townName | string | null | City, town, or village name. Default: null. Examples: "Paris", "Stockholm", "Reykjavík". |
remittance_information — RemittanceInformation
Free-text and/or structured remittance information for a transaction. Profile of: ISO 20022 RemittanceInformation. Servers SHOULD populate this only when remittance info is genuinely present and not just a duplicate of Transaction.description.
| Field | Type | Required | Description |
|---|---|---|---|
creditorReference | string | null | Structured creditor reference, typically an ISO 11649 RF-prefixed reference. The reference is opaque to bank2ai; servers pass it through as the bank exposes it. Default: null. Examples: "RF18539007547034". | |
unstructured | string | null | Free-text remittance line (e.g., the SEPA RemittanceInformation/Unstructured field). Default: null. |
Raw JSON Schema
{
"additionalProperties": false,
"properties": {
"amount": {
"description": "Instructed amount in `currency`.",
"exclusiveMinimum": 0,
"type": "number"
},
"creditor": {
"description": "Creditor record. `accountIdentifier` is required for routing; `name` is required for display and Confirmation-of-Payee on rails that support it.",
"properties": {
"accountIdentifier": {
"anyOf": [
{
"description": "Discriminated union of typed account identifiers. Profile of: ISO 20022 `AccountIdentification4Choice`.",
"oneOf": [
{
"description": "IBAN-routed account, ISO 13616.",
"properties": {
"iban": {
"description": "IBAN, ISO 13616.",
"examples": [
"GB29NWBK60161331926819",
"DE89370400440532013000"
],
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"type": "string"
},
"type": {
"const": "iban",
"default": "iban",
"description": "Discriminator: `iban`.",
"type": "string"
}
},
"required": [
"iban"
],
"type": "object"
},
{
"description": "Domestic Basic Bank Account Number, used in markets without an IBAN.",
"properties": {
"bban": {
"description": "Domestic account identifier in the country's native format.",
"examples": [
"0133-26-007890"
],
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"IS",
"GB"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"type": {
"const": "bban",
"default": "bban",
"description": "Discriminator: `bban`.",
"type": "string"
}
},
"required": [
"bban",
"country"
],
"type": "object"
},
{
"description": "Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).",
"properties": {
"accountNumber": {
"description": "Account number in the country's native format.",
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"US",
"GB"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"routing": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "US ABA routing number, when applicable."
},
"sortCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "UK sort code, when applicable."
},
"type": {
"const": "accountNumber",
"default": "accountNumber",
"description": "Discriminator: `accountNumber`.",
"type": "string"
}
},
"required": [
"accountNumber",
"country"
],
"type": "object"
},
{
"description": "Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).",
"properties": {
"alias": {
"description": "The alias value as the user knows it.",
"examples": [
"alex@upi",
"+44-7700-900000"
],
"type": "string"
},
"aliasType": {
"description": "Kind of alias.",
"enum": [
"email",
"phone",
"vpa",
"pix",
"other"
],
"type": "string"
},
"type": {
"const": "alias",
"default": "alias",
"description": "Discriminator: `alias`.",
"type": "string"
}
},
"required": [
"alias",
"aliasType"
],
"type": "object"
}
]
},
{
"type": "null"
}
],
"default": null,
"description": "Party's account identifier when known."
},
"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 party's bank, ISO 9362.",
"examples": [
"NWBKGB2L"
]
},
"brandName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Brand or chain name the party belongs to, when `name` is a specific outlet of a larger brand. For card transactions this is the merchant's parent brand (e.g. `name` = \"Starbucks Reserve Roastery\", `brandName` = \"Starbucks\"). Clients MAY use `brandName` to group transactions by chain while still displaying the specific outlet on each row.",
"examples": [
"Starbucks",
"Bónus"
]
},
"latitude": {
"anyOf": [
{
"maximum": 90,
"minimum": -90,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Geographic latitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group `geoLocation` (latitude component).",
"examples": [
48.8566,
64.1466
]
},
"longitude": {
"anyOf": [
{
"maximum": 180,
"minimum": -180,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Geographic longitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group `geoLocation` (longitude component).",
"examples": [
2.3522,
-21.9426
]
},
"name": {
"description": "Party's full name or business name.",
"type": "string"
},
"nationalId": {
"anyOf": [
{
"description": "Person or business national identifier.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"IS",
"US"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"type": {
"anyOf": [
{
"description": "Opaque label for the kind of national identifier carried in `NationalId.value`.\n\nbank2ai does not validate national-ID formats; this is a hint so\nclients can render or route appropriately. Servers SHOULD set the\nclosest-matching value or use `other`.",
"enum": [
"ssn",
"kennitala",
"cpr",
"personnummer",
"cpf",
"other"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hint for the kind of identifier. bank2ai does not validate the value."
},
"value": {
"description": "National identifier value, in the country's native format.",
"examples": [
"010190-1234",
"123-45-6789"
],
"type": "string"
}
},
"required": [
"value",
"country"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Party's national identifier when known."
},
"postalAddress": {
"anyOf": [
{
"description": "Postal address of a party or card-acceptor merchant.\n\nProfile of: ISO 20022 `PostalAddress24` (subset). Aligns with the\nOpen Finance / Berlin Group `cardAcceptorAddress` structure so card\ntransactions can surface where the swipe happened. Servers SHOULD\npopulate whichever subfields the bank exposes and omit the rest;\n`townName` and `country` are the most commonly available and the\nmost useful for LLM context.",
"properties": {
"addressLine": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-form address lines, used when the bank exposes the address as unparsed text. Servers SHOULD prefer the typed fields above and fall back to `addressLine` only when they cannot decompose the address."
},
"buildingNumber": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Building number on the street.",
"examples": [
"12",
"12B"
]
},
"country": {
"anyOf": [
{
"pattern": "^[A-Z]{2}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"FR",
"SE",
"IS",
"US"
]
},
"countrySubDivision": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "State, province, region, or other top-level subdivision.",
"examples": [
"CA",
"Île-de-France"
]
},
"postCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Postal / ZIP code.",
"examples": [
"75001",
"SW1A 1AA"
]
},
"streetName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Street name without the building number.",
"examples": [
"Rue de Rivoli"
]
},
"townName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "City, town, or village name.",
"examples": [
"Paris",
"Stockholm",
"Reykjavík"
]
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Postal address of the party. For card transactions, this is the merchant / card-acceptor address (Open Finance `cardAcceptorAddress`). Servers SHOULD populate whatever subset they have, typically at least `townName` and `country`."
}
},
"required": [
"name"
],
"type": "object"
},
"currency": {
"description": "ISO 4217 currency code of the instructed amount.",
"examples": [
"ISK",
"EUR",
"USD"
],
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"debtor_account_id": {
"description": "Source `Account.id` from `get-accounts`.",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-text shown on the counterparty's statement. Falls back to `remittance_information.unstructured` when both are set."
},
"end_to_end_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional client-supplied ISO 20022 cross-rail identifier. Servers MUST generate one when the client omits it; the resolved value is echoed in the response summary."
},
"idempotency_key": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional idempotency key, scoped to this tool. Servers SHOULD return the original prepared-transfer response for repeat calls with the same key within at least 24 hours."
},
"local_instrument": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Rail-specific instrument code; `INST` for SEPA Instant, `RTGS` for SWIFT, etc. Free-form per rail."
},
"rail": {
"description": "Settlement rail. Drives validation, fees, and the set of meaningful `local_instrument` values.",
"enum": [
"domestic-IS",
"sepa",
"sepa-instant",
"swift"
],
"type": "string"
},
"remittance_information": {
"anyOf": [
{
"description": "Free-text and/or structured remittance information for a transaction.\n\nProfile of: ISO 20022 `RemittanceInformation`. Servers SHOULD populate\nthis only when remittance info is genuinely present and not just a\nduplicate of `Transaction.description`.",
"properties": {
"creditorReference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Structured creditor reference, typically an ISO 11649 RF-prefixed reference. The reference is opaque to bank2ai; servers pass it through as the bank exposes it.",
"examples": [
"RF18539007547034"
]
},
"unstructured": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-text remittance line (e.g., the SEPA `RemittanceInformation/Unstructured` field)."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Structured / unstructured remittance information to attach to the transfer."
},
"requested_execution_date": {
"anyOf": [
{
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 (YYYY-MM-DD) requested execution date. Omit for as-soon-as-possible per the rail."
}
},
"required": [
"debtor_account_id",
"creditor",
"amount",
"currency",
"rail"
],
"type": "object"
}
Output
| Field | Type | Required | Description |
|---|---|---|---|
actions | array<TransferAction> | Optional follow-up actions the client may surface. | |
code | string | null | Server-defined code identifying a recoverable error (e.g., insufficient_funds, invalid_account, missing_creditor_identifier). Omitted on success. Default: null. | |
content | string | ✓ | Human-readable status message. |
item | PreparedTransfer | null | Prepared transfer details when validation succeeded. Default: null. |
actions[] — TransferAction
Suggested follow-up action for a prepared transfer.
| Field | Type | Required | Description |
|---|---|---|---|
link | string | ✓ | Target URL or in-app link to perform the action. |
title | string | ✓ | Human-readable label for the action. |
item — PreparedTransfer
Result of a successful prepare-transfer call. transferIntentId is the opaque token the client passes to execute-transfer. summary is what the user confirms; everything else is supporting metadata (fees, FX, payee verification, warnings).
| Field | Type | Required | Description |
|---|---|---|---|
confirmationOfPayee | ConfirmationOfPayee | null | Payee verification outcome. Servers on rails that support Confirmation of Payee / Verification of Payee MUST populate this when known. Servers on rails that do not SHOULD omit. Default: null. | |
estimatedSettlement | string | null | ISO 8601 estimated settlement time at the creditor. Default: null. | |
expiresAt | string | ✓ | ISO 8601 timestamp after which execute-transfer will reject the intent. Servers SHOULD set this 5 minutes ahead of the prepare time; rails MAY shorten or extend. |
fees | array<TransferFee> | null | Fees the bank will charge for this transfer. Default: null. | |
fx | TransferFx | null | FX details when the transfer crosses currencies. Default: null. | |
summary | TransferSummary | ✓ | Validated echo of the prepare-transfer inputs; the user-facing confirmation surface. |
transferIntentId | string | ✓ | Opaque intent token; pass to execute-transfer. |
warnings | array<TransferWarning> | null | Advisory or blocking warnings emitted during validation. Default: null. |
confirmationOfPayee — ConfirmationOfPayee
Result of a payee-name verification against the destination account.
| Field | Type | Required | Description |
|---|---|---|---|
status | "match" | "close-match" | "no-match" | "unavailable" | ✓ | Verification outcome. |
suggestedName | string | null | On a close-match or no-match, the actual name on the destination account when the rail returns it. Default: null. |
fees[] — TransferFee
One fee line item that will apply to the transfer.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | ✓ | Fee amount in currency. |
currency | string | ✓ | ISO 4217 currency code. Pattern: ^[A-Z]{3}$. |
description | string | null | Human-readable label for the fee. Default: null. Examples: "Wire fee", "FX margin". |
fx — TransferFx
Foreign-exchange details for a cross-currency transfer.
| Field | Type | Required | Description |
|---|---|---|---|
lockedUntil | string | null | ISO 8601 timestamp until which the quoted rate is held. Default: null. | |
rate | number | ✓ | Exchange rate applied (sourceAmount * rate = targetAmount). |
sourceAmount | number | ✓ | Amount debited from the debtor account. |
sourceCurrency | string | ✓ | Currency of the debtor account. Pattern: ^[A-Z]{3}$. |
targetAmount | number | ✓ | Amount credited to the creditor. |
targetCurrency | string | ✓ | Currency the creditor receives. Pattern: ^[A-Z]{3}$. |
summary — TransferSummary
Validated echo of the prepare-transfer inputs; the user-facing confirmation surface.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | ✓ | Transfer amount in currency. |
creditor | Party | ✓ | Validated creditor record. The accountIdentifier field carries the routing identifier; servers MUST populate it. |
currency | string | ✓ | ISO 4217 currency code of the instructed amount. Examples: "ISK", "EUR", "USD". Pattern: ^[A-Z]{3}$. |
debtorAccount | Account | ✓ | Resolved snapshot of the debtor (source) account. |
description | string | null | Free-text shown on the counterparty's statement. Falls back to remittanceInformation.unstructured when both are present. Default: null. | |
endToEndId | string | ✓ | ISO 20022 cross-rail identifier. Server-generated when the client did not supply one; populated either way so the client can show / audit the value. |
localInstrument | string | null | Rail-specific local instrument code (e.g., INST for SEPA Instant). Default: null. | |
rail | "domestic-IS" | "sepa" | "sepa-instant" | "swift" | ✓ | Settlement rail. |
remittanceInformation | RemittanceInformation | null | Remittance information, when present. Default: null. | |
requestedExecutionDate | string | null | Requested execution date, ISO 8601. Omitted means as-soon-as-possible per the rail's defaults. Default: null. |
creditor — Party
Validated creditor record. The accountIdentifier field carries the routing identifier; servers MUST populate it.
| Field | Type | Required | Description |
|---|---|---|---|
accountIdentifier | IbanIdentifier | BbanIdentifier | AccountNumberIdentifier | AliasIdentifier | null | Party's account identifier when known. Default: null. | |
bic | string | null | BIC / SWIFT code of the party's bank, ISO 9362. Default: null. Examples: "NWBKGB2L". | |
brandName | string | null | Brand or chain name the party belongs to, when name is a specific outlet of a larger brand. For card transactions this is the merchant's parent brand (e.g. name = "Starbucks Reserve Roastery", brandName = "Starbucks"). Clients MAY use brandName to group transactions by chain while still displaying the specific outlet on each row. Default: null. Examples: "Starbucks", "Bónus". | |
latitude | number | null | Geographic latitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group geoLocation (latitude component). Default: null. Examples: 48.8566, 64.1466. | |
longitude | number | null | Geographic longitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group geoLocation (longitude component). Default: null. Examples: 2.3522, -21.9426. | |
name | string | ✓ | Party's full name or business name. |
nationalId | NationalId | null | Party's national identifier when known. Default: null. | |
postalAddress | PostalAddress | null | Postal address of the party. For card transactions, this is the merchant / card-acceptor address (Open Finance cardAcceptorAddress). Servers SHOULD populate whatever subset they have, typically at least townName and country. Default: null. |
debtorAccount — Account
Resolved snapshot of the debtor (source) account.
| 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 | "Current" | "Credit" | "Savings" | "Loan" | "Other" | 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 | "Enabled" | "Blocked" | "Deleted" | null | Lifecycle status. If omitted, clients SHOULD treat the account as Enabled. Default: null. | |
usage | "Private" | "Business" | null | Whether this is a personal or business account. Default: null. |
remittanceInformation — RemittanceInformation
Free-text and/or structured remittance information for a transaction. Profile of: ISO 20022 RemittanceInformation. Servers SHOULD populate this only when remittance info is genuinely present and not just a duplicate of Transaction.description.
| Field | Type | Required | Description |
|---|---|---|---|
creditorReference | string | null | Structured creditor reference, typically an ISO 11649 RF-prefixed reference. The reference is opaque to bank2ai; servers pass it through as the bank exposes it. Default: null. Examples: "RF18539007547034". | |
unstructured | string | null | Free-text remittance line (e.g., the SEPA RemittanceInformation/Unstructured field). Default: null. |
warnings[] — TransferWarning
Server-emitted advisory about a prepared transfer. Used for AML hits, sanctions matches, unusual-amount notices, etc. severity: "block" indicates the server will refuse execute-transfer against this intent unless the user explicitly overrides.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | ✓ | Server-defined warning code. |
message | string | ✓ | Human-readable explanation. |
severity | "info" | "warn" | "block" | ✓ | Warning severity. |
Raw JSON Schema
{
"description": "Envelope for `prepare-transfer`. Recoverable-error pattern: when\nvalidation succeeded `item` is populated; when it failed `content`\nexplains why and `item` is omitted.",
"properties": {
"actions": {
"description": "Optional follow-up actions the client may surface.",
"items": {
"description": "Suggested follow-up action for a prepared transfer.",
"properties": {
"link": {
"description": "Target URL or in-app link to perform the action.",
"type": "string"
},
"title": {
"description": "Human-readable label for the action.",
"type": "string"
}
},
"required": [
"title",
"link"
],
"type": "object"
},
"type": "array"
},
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Server-defined code identifying a recoverable error (e.g., `insufficient_funds`, `invalid_account`, `missing_creditor_identifier`). Omitted on success."
},
"content": {
"description": "Human-readable status message.",
"type": "string"
},
"item": {
"anyOf": [
{
"description": "Result of a successful `prepare-transfer` call.\n\n`transferIntentId` is the opaque token the client passes to\n`execute-transfer`. `summary` is what the user confirms; everything\nelse is supporting metadata (fees, FX, payee verification, warnings).",
"properties": {
"confirmationOfPayee": {
"anyOf": [
{
"description": "Result of a payee-name verification against the destination account.",
"properties": {
"status": {
"description": "Verification outcome.",
"enum": [
"match",
"close-match",
"no-match",
"unavailable"
],
"type": "string"
},
"suggestedName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "On a `close-match` or `no-match`, the actual name on the destination account when the rail returns it."
}
},
"required": [
"status"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Payee verification outcome. Servers on rails that support Confirmation of Payee / Verification of Payee MUST populate this when known. Servers on rails that do not SHOULD omit."
},
"estimatedSettlement": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 estimated settlement time at the creditor."
},
"expiresAt": {
"description": "ISO 8601 timestamp after which `execute-transfer` will reject the intent. Servers SHOULD set this 5 minutes ahead of the prepare time; rails MAY shorten or extend.",
"format": "date-time",
"type": "string"
},
"fees": {
"anyOf": [
{
"items": {
"description": "One fee line item that will apply to the transfer.",
"properties": {
"amount": {
"description": "Fee amount in `currency`.",
"type": "number"
},
"currency": {
"description": "ISO 4217 currency code.",
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Human-readable label for the fee.",
"examples": [
"Wire fee",
"FX margin"
]
}
},
"required": [
"amount",
"currency"
],
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Fees the bank will charge for this transfer."
},
"fx": {
"anyOf": [
{
"description": "Foreign-exchange details for a cross-currency transfer.",
"properties": {
"lockedUntil": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp until which the quoted rate is held."
},
"rate": {
"description": "Exchange rate applied (sourceAmount * rate = targetAmount).",
"type": "number"
},
"sourceAmount": {
"description": "Amount debited from the debtor account.",
"type": "number"
},
"sourceCurrency": {
"description": "Currency of the debtor account.",
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"targetAmount": {
"description": "Amount credited to the creditor.",
"type": "number"
},
"targetCurrency": {
"description": "Currency the creditor receives.",
"pattern": "^[A-Z]{3}$",
"type": "string"
}
},
"required": [
"rate",
"sourceAmount",
"sourceCurrency",
"targetAmount",
"targetCurrency"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "FX details when the transfer crosses currencies."
},
"summary": {
"description": "Validated echo of the prepare-transfer inputs; the user-facing confirmation surface.",
"properties": {
"amount": {
"description": "Transfer amount in `currency`.",
"exclusiveMinimum": 0,
"type": "number"
},
"creditor": {
"description": "Validated creditor record. The `accountIdentifier` field carries the routing identifier; servers MUST populate it.",
"properties": {
"accountIdentifier": {
"anyOf": [
{
"description": "Discriminated union of typed account identifiers. Profile of: ISO 20022 `AccountIdentification4Choice`.",
"oneOf": [
{
"description": "IBAN-routed account, ISO 13616.",
"properties": {
"iban": {
"description": "IBAN, ISO 13616.",
"examples": [
"GB29NWBK60161331926819",
"DE89370400440532013000"
],
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"type": "string"
},
"type": {
"const": "iban",
"default": "iban",
"description": "Discriminator: `iban`.",
"type": "string"
}
},
"required": [
"iban"
],
"type": "object"
},
{
"description": "Domestic Basic Bank Account Number, used in markets without an IBAN.",
"properties": {
"bban": {
"description": "Domestic account identifier in the country's native format.",
"examples": [
"0133-26-007890"
],
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"IS",
"GB"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"type": {
"const": "bban",
"default": "bban",
"description": "Discriminator: `bban`.",
"type": "string"
}
},
"required": [
"bban",
"country"
],
"type": "object"
},
{
"description": "Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).",
"properties": {
"accountNumber": {
"description": "Account number in the country's native format.",
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"US",
"GB"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"routing": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "US ABA routing number, when applicable."
},
"sortCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "UK sort code, when applicable."
},
"type": {
"const": "accountNumber",
"default": "accountNumber",
"description": "Discriminator: `accountNumber`.",
"type": "string"
}
},
"required": [
"accountNumber",
"country"
],
"type": "object"
},
{
"description": "Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).",
"properties": {
"alias": {
"description": "The alias value as the user knows it.",
"examples": [
"alex@upi",
"+44-7700-900000"
],
"type": "string"
},
"aliasType": {
"description": "Kind of alias.",
"enum": [
"email",
"phone",
"vpa",
"pix",
"other"
],
"type": "string"
},
"type": {
"const": "alias",
"default": "alias",
"description": "Discriminator: `alias`.",
"type": "string"
}
},
"required": [
"alias",
"aliasType"
],
"type": "object"
}
]
},
{
"type": "null"
}
],
"default": null,
"description": "Party's account identifier when known."
},
"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 party's bank, ISO 9362.",
"examples": [
"NWBKGB2L"
]
},
"brandName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Brand or chain name the party belongs to, when `name` is a specific outlet of a larger brand. For card transactions this is the merchant's parent brand (e.g. `name` = \"Starbucks Reserve Roastery\", `brandName` = \"Starbucks\"). Clients MAY use `brandName` to group transactions by chain while still displaying the specific outlet on each row.",
"examples": [
"Starbucks",
"Bónus"
]
},
"latitude": {
"anyOf": [
{
"maximum": 90,
"minimum": -90,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Geographic latitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group `geoLocation` (latitude component).",
"examples": [
48.8566,
64.1466
]
},
"longitude": {
"anyOf": [
{
"maximum": 180,
"minimum": -180,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Geographic longitude of the party's location in decimal degrees (WGS 84). For card transactions, this is the merchant / card-acceptor location. Profile of: Berlin Group `geoLocation` (longitude component).",
"examples": [
2.3522,
-21.9426
]
},
"name": {
"description": "Party's full name or business name.",
"type": "string"
},
"nationalId": {
"anyOf": [
{
"description": "Person or business national identifier.",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"IS",
"US"
],
"pattern": "^[A-Z]{2}$",
"type": "string"
},
"type": {
"anyOf": [
{
"description": "Opaque label for the kind of national identifier carried in `NationalId.value`.\n\nbank2ai does not validate national-ID formats; this is a hint so\nclients can render or route appropriately. Servers SHOULD set the\nclosest-matching value or use `other`.",
"enum": [
"ssn",
"kennitala",
"cpr",
"personnummer",
"cpf",
"other"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hint for the kind of identifier. bank2ai does not validate the value."
},
"value": {
"description": "National identifier value, in the country's native format.",
"examples": [
"010190-1234",
"123-45-6789"
],
"type": "string"
}
},
"required": [
"value",
"country"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Party's national identifier when known."
},
"postalAddress": {
"anyOf": [
{
"description": "Postal address of a party or card-acceptor merchant.\n\nProfile of: ISO 20022 `PostalAddress24` (subset). Aligns with the\nOpen Finance / Berlin Group `cardAcceptorAddress` structure so card\ntransactions can surface where the swipe happened. Servers SHOULD\npopulate whichever subfields the bank exposes and omit the rest;\n`townName` and `country` are the most commonly available and the\nmost useful for LLM context.",
"properties": {
"addressLine": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-form address lines, used when the bank exposes the address as unparsed text. Servers SHOULD prefer the typed fields above and fall back to `addressLine` only when they cannot decompose the address."
},
"buildingNumber": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Building number on the street.",
"examples": [
"12",
"12B"
]
},
"country": {
"anyOf": [
{
"pattern": "^[A-Z]{2}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 3166-1 alpha-2 country code.",
"examples": [
"FR",
"SE",
"IS",
"US"
]
},
"countrySubDivision": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "State, province, region, or other top-level subdivision.",
"examples": [
"CA",
"Île-de-France"
]
},
"postCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Postal / ZIP code.",
"examples": [
"75001",
"SW1A 1AA"
]
},
"streetName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Street name without the building number.",
"examples": [
"Rue de Rivoli"
]
},
"townName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "City, town, or village name.",
"examples": [
"Paris",
"Stockholm",
"Reykjavík"
]
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Postal address of the party. For card transactions, this is the merchant / card-acceptor address (Open Finance `cardAcceptorAddress`). Servers SHOULD populate whatever subset they have, typically at least `townName` and `country`."
}
},
"required": [
"name"
],
"type": "object"
},
"currency": {
"description": "ISO 4217 currency code of the instructed amount.",
"examples": [
"ISK",
"EUR",
"USD"
],
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"debtorAccount": {
"description": "Resolved snapshot of the debtor (source) account.",
"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"
],
"type": "string"
},
"accountType": {
"anyOf": [
{
"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"
],
"type": "string"
},
{
"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."
},
"balance": {
"description": "Current booked balance in `currency`. For credit accounts a negative value indicates an outstanding balance owed.",
"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."
},
"balances": {
"anyOf": [
{
"items": {
"description": "One typed balance entry on an account.\n\nProfile of: Berlin Group PSD2 `balances` array element.",
"properties": {
"amount": {
"description": "Balance amount in `currency`.",
"type": "number"
},
"asOf": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp when this balance was last refreshed."
},
"currency": {
"description": "ISO 4217 currency code.",
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"type": {
"description": "Balance type.",
"enum": [
"ClosingBooked",
"Expected",
"InterimAvailable",
"ForwardAvailable",
"NonInvoiced"
],
"type": "string"
}
},
"required": [
"type",
"amount",
"currency"
],
"type": "object"
},
"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."
},
"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"
]
},
"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"
]
},
"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}$",
"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"
]
},
"id": {
"description": "Unique account identifier (server-scoped)",
"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."
},
"isWithdrawalAccount": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether this account can be used as the source of an outgoing transfer or withdrawal."
},
"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"
]
},
"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."
},
"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"
]
},
"openedDate": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Date the account was opened, ISO 8601 (YYYY-MM-DD)."
},
"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`."
},
"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"
]
},
"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."
},
"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"
]
},
"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."
},
"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."
},
"status": {
"anyOf": [
{
"description": "Lifecycle status of an account, per Berlin Group PSD2 `accountStatus`.",
"enum": [
"Enabled",
"Blocked",
"Deleted"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Lifecycle status. If omitted, clients SHOULD treat the account as `Enabled`."
},
"usage": {
"anyOf": [
{
"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"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether this is a personal or business account."
}
},
"required": [
"id",
"accountNumber",
"currency",
"balance"
],
"type": "object"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-text shown on the counterparty's statement. Falls back to `remittanceInformation.unstructured` when both are present."
},
"endToEndId": {
"description": "ISO 20022 cross-rail identifier. Server-generated when the client did not supply one; populated either way so the client can show / audit the value.",
"type": "string"
},
"localInstrument": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Rail-specific local instrument code (e.g., `INST` for SEPA Instant)."
},
"rail": {
"description": "Settlement rail.",
"enum": [
"domestic-IS",
"sepa",
"sepa-instant",
"swift"
],
"type": "string"
},
"remittanceInformation": {
"anyOf": [
{
"description": "Free-text and/or structured remittance information for a transaction.\n\nProfile of: ISO 20022 `RemittanceInformation`. Servers SHOULD populate\nthis only when remittance info is genuinely present and not just a\nduplicate of `Transaction.description`.",
"properties": {
"creditorReference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Structured creditor reference, typically an ISO 11649 RF-prefixed reference. The reference is opaque to bank2ai; servers pass it through as the bank exposes it.",
"examples": [
"RF18539007547034"
]
},
"unstructured": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Free-text remittance line (e.g., the SEPA `RemittanceInformation/Unstructured` field)."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Remittance information, when present."
},
"requestedExecutionDate": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Requested execution date, ISO 8601. Omitted means as-soon-as-possible per the rail's defaults."
}
},
"required": [
"debtorAccount",
"creditor",
"amount",
"currency",
"rail",
"endToEndId"
],
"type": "object"
},
"transferIntentId": {
"description": "Opaque intent token; pass to `execute-transfer`.",
"type": "string"
},
"warnings": {
"anyOf": [
{
"items": {
"description": "Server-emitted advisory about a prepared transfer.\n\nUsed for AML hits, sanctions matches, unusual-amount notices, etc.\n`severity: \"block\"` indicates the server will refuse `execute-transfer`\nagainst this intent unless the user explicitly overrides.",
"properties": {
"code": {
"description": "Server-defined warning code.",
"type": "string"
},
"message": {
"description": "Human-readable explanation.",
"type": "string"
},
"severity": {
"description": "Warning severity.",
"enum": [
"info",
"warn",
"block"
],
"type": "string"
}
},
"required": [
"code",
"message",
"severity"
],
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Advisory or blocking warnings emitted during validation."
}
},
"required": [
"transferIntentId",
"expiresAt",
"summary"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Prepared transfer details when validation succeeded."
}
},
"required": [
"content"
],
"type": "object"
}