# Get Account Details source: https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/get-account-details/index.md ## Request overview {#request-overview} The goal of this request is to retrieve from the Account Servicing Payment Service Provider (ASPSP), using the `consentId` which is part of previously obtained consent object, . This flow assumes the Payment Service User (PSU) has already consented to this access and the ASPSP system stores this record of consent or `consentId`. For more information, see [Account Information Consent Request](https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/account-information-consent/index.md). ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-------------------------|------------|-----------------------------------------------------------------------------------------------------------------------|-------------------------| | /accounts/account | `POST` | CMA9, Polish API, NextGenPSD2, STET, Czech Open Banking Standard API Profile, Slovak Banking API Standard API Profile | Returns account details | The following sequence diagram shows the flow for obtaining the details of a PSU's accounts. Diagram get_account_details ## Request scenario {#request-scenario} API Reference: `POST /accounts/account` #### Request header {#request-header} N/A #### Request body {#request-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `requestInfo` | Includes information about the request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | A set of elements used to define the request details | N/A | | `xRequestId` | The ID of the request, unique to the call, as determined by the TPP | TPP | A memorable ID could be used to support in a dispute | M | 1..1 | String UUID | Free field that allows for the addition of information that can be referenced for future use | 36 pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `consentId` | A unique reference to the account information consent stored by the ASPSP. This is required to enable subsequent account information requests related to the consent (for example, to request account or transaction details) | ASPSP | Pass this value as part of the account information requests related to the consent. | M | 1..1 | String | A unique reference to the account information consent stored by the ASPSP. Please note that this is not the original value generated by the ASPSP but a generated 'proxy' value related to that. | 1-256 | | `aspspId` | ID of a financial institution servicing the accounts of the PSU | ASPSP | Identification of ASPSP | M | 1..1 | String UUID | This element is used to specify the identification code of a financial institution which holds PSU accounts | 36 pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `isLivePsuRequest` | Indicates if PSU actively initiated the request | ASPSP | Type of PSU request | O | 0..1 | Boolean | PSU request type | Boolean: true or false | | `psuIPAddress` | An IP address between PSU and TPP | ASPSP | It shall be contained only if the PSU actively initiated this request | C | 0..1 | String | IP address of PSU's terminal device | 1-256 Required when isLivePsuRequest=true pattern: `(^(([0-9]` \| `[1-9][0-9]` \| `1[0-9]{2}` \| `2[0-4][0-9]` \| `25[0-5])\.){3}([0-9]` \| `[1-9][0-9]` \| `1[0-9]{2}` \| `2[0-4][0-9]` \| `25[0-5])$)` \| `(^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}` \| `([0-9a-fA-F]{1,4}:){1,7}:` \| `([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}` \| `([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}` \| `([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}` \| `([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}` \| `([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}` \| `[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})` \| `:((:[0-9a-fA-F]{1,4}){1,7}` \| `:)` \| `fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}` \| `::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])` \| `([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9]))$)` | | `psuAgent` | Indicates the user-agent for the PSU. If the PSU is using the TPP's mobile app, make sure the mobile app user-agent string is different than browser-based user-agent strings. | ASPSP | If a user-agent is supplied to ASPSP, then this information can be used by ASPSP's security mechanisms. To avoid rejections, it is recommended to include this field when providing `isLivePsuRequest` and `psuIPAddress`. | O | 0..1 | String | PSU's browser agent details | 1-256 | | `psuTppCustomerId` | For billing purposes | MC | Used for identifying the number of transactions related to a certain PSU | O | 0..1 | String | Identifier of the PSU in the TPP system used for billing. | 1-256 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purposes | O | 0..1 | Object | A set of elements used to define the merchant details | N/A | | `id` | Merchant identification code to identify the merchant | MC | Unique Merchant identifier per TPP, which could be used for reporting/reconciliation purposes | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant ID | 1-256 | | `name` | Merchant name to identify the merchant | MC | Name of merchant | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant name | 1-256 | | `accountId` | A unique identifier is used to identify the account resource. | ASPSP | Identifier of the addressed account (Use the ID received in Get List of Accounts response -- in the `resourceId` field) | M | 1..1 | String | Account reference identification as returned in the list of accounts | 1-256 | Tip: For an explanation of notations used, refer to **Open Banking General FAQ** in our [Frequently Asked Questions](https://developer.mastercard.com/open-banking-connect/documentation/frequently-asked-questions/index.md) section. ### Response -- Success {#response--success} HTTP Response Code = 200, OK Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). For specific error codes for this feature, see **Feature specific error codes** below. #### Response header {#response-header} N/A #### Response body {#response-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------|-----------------|------------------------------------------------------------------------------------------|---------------|------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `originalRequestInfo` | Returns original request information to the TPP | MC | This object contains original request information | M | 1..1 | Object | Original request information received from the TPP | N/A | | `xRequestId` | A memorable ID which could be used to support in a dispute | TPP | This element could be used for request-response tracking | M | 1..1 | String UUID | Original xRequestId given by the client on request | 36 pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `account` | Unambiguous identification of the account to which credit and debit entries are made | TPP | Used to encapsulate accounts data | O | 0..1 | Object | A set of elements used to define the account details | N/A | | `resourceId` | A unique identifier is used to identify the account resource. This identifier has no meaning to the account owner. | TPP | This value should be used to make subsequent account-specific requests | M | 1..1 | String | Account reference identification | 1-256 | | `currency` | Identification of the currency in which the account is held. | TPP | Currency of account | O | 0..1 | String | Account currency | ISO 4217 ALPHA 3 CHAR pattern: \^\[A-Z\]{3}$ | | `accountHolderType` | Specifies account main type: Personal or business | TPP | Account holder type | O | 0..1 | Enum | Specifies the type of account | Enum: `Business`, `Personal` | | `accountType` | Specifies the sub-type of the account: Savings, credit card, current, and so on. | TPP | Sub-type of account | O | 0..1 | String | Specifies the sub-type of account (product family group) | 1-256 Values returned as one of the following codes, aligned with ExternalCashAccountType1Code list from [ISO 20022 external codes](https://www.iso20022.org/external_code_list.page). \[`CACC`, `CASH`, `CHAR`, `CISH`, `COMM`, `CPAC`, `LLSV`, `LOAN`, `MGLD`, `MOMA`, `NREX`, `ODFT`, `ONDP`, `OTHR`, `SACC`, `SLRY`, `SVGS`, `TAXE`, `TRAN`, `TRAS`, `CARD`\] | | `nameClient` | The nickname of the account assigned by the account owner to provide an additional means of identification of the account. | TPP | Account name defined by account owner | O | 0..1 | String | Account's name client (defined by account owner) | 1-256 | | `name` | The account name is the name or names of the account owner(s) represented at an account level, as displayed by the ASPSP's online channels | TPP | Account name defined by ASPSP | O | 0..1 | String | Account name (defined by ASPSP) | 1-256 | | `holderName` | The name by which a party is known, and which is usually used to identify that party. | TPP | This element is used to specify account holder name | O | 0..1 | String | Account Holder name | 1-256 | | `holderAddress` | Account holder address split in separate address fields | TPP | This element encapsulates the account holder address | O | 0..1 | Object | Set of elements used to define the holder address details (future use) | N/A | | `street` | Name of a street | TPP | This element is used to specify the street name | O | 0..1 | String | Street name | 1-70 | | `buildingNumber` | A number that identifies the position of a building on a street. | TPP | This element is used to specify the building number | O | 0..1 | String | Building Number | 1-256 | | `city` | Name of a built-up area, with defined boundaries, and a local government. | TPP | This element is used to specify the city name | O | 0..1 | String | City name | 1-256 | | `postalCode` | Identifier consisting of a group of letters and, or, numbers that are added to a postal address to assist the sorting of mail. | TPP | This element is used to specify the post code | O | 0..1 | String | Postal code | 1-256 | | `countrySubDivision` | Identifies a subdivision of a country such as state, region, county. | TPP | This element is used to specify the county code | O | 0..1 | String | County name | 1-256 | | `country` | A nation with its own government | TPP | This element is used to specify the country code | O | 0..1 | String | Country name | ISO 3166 ALPHA 2 CHAR pattern: `^[A-Z]{2}$` | | `holderNameAddress` | Contains account holder name and address | TPP | An array which specifies the account holder's name and address | O | 0..4 | String | Account holder's name and address | | | `accountPsuRelations` | Describes relation between PSU and account | TPP | PSU relation to account | O | 0..1 | Object | Description of relations between PSU and an Account | - | | `typeOfRelation` | Specifies relation between PSU and account | TPP | Can be used for filtering the results by type of relation between the PSU and an account | O | 0..1 | String | Type of relation between PSU and an account | - | | `accountNumber` | Specifies the account number identification as set by ASPSP | TPP | Account number defined by ASPSP | O | 0..1 | String | Account number as assigned by the ASPSP. In case schemeName is "SortCodeAccountNumber", the first 6 digits are the sort code followed by 8 digits forming the account number. | - | | `schemeName` | Specifies the scheme name of the account number | TPP | Scheme name of the account number defined by ASPSP | O | 0..1 | String | Name of the account number's scheme. Will return one of: "SortCodeAccountNumber", "IBAN", "BBAN", "PAN". | - | | `auxData` | ASPSPs use this object to provide additional account details | TPP | Contains additional fields included by ASPSPs | O | 0..1 | Object | A set of elements used to define additional account details. Data map `<\string, string>`. | Specific to additional account details provided in response by the ASPSPs supporting Polish API profile. | ## Feature-specific error codes {#feature-specific-error-codes} Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | "Conditional field psuIPAddress is expected when `isLivePsuRequest`=true" | `FORMAT_ERROR` | "IP address" field is mandatory if parameter "isLivePsuRequest"=true. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | Typically occurs because the TPP has provided in request `isLivePsuRequest`=true and did not provide the IP address value. | Provide IP address of PSU in the request when providing `isLivePsuRequest`=true | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Conditional field psuIPAddress is expected when isLivePsuRequest='true'", "Details": "path[0]=/requestInfo/psuIPAddress" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------|-----------------|----------------------------------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------| | "The Access Token associated with the Request has expired" | `INVALID_TOKEN` | The Access Token associated with the request has expired | N/A | This typically occurs when the consent that the TPP has previously obtained from a PSU has expired. | PSU needs to provide a new consent. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " INVALID_TOKEN ", "Description": "Access Token associated with the Request has expired" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------|-----------------|----------------------------------------------------------|-----------------------|------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Access Token associated with the request is invalid or has been revoked" | `INVALID_TOKEN` | The consent ID used in the request is invalid or revoked | N/A | This typically occurs when the consent ID is invalid or revoked. | Ensure a valid consent ID is used in the request. If you think the specified consent ID is valid please contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_TOKEN", "Description": "Access Token associated with the Request is invalid or has been revoked" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------|------------------|-----------------------------------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | "Provided account is invalid or unlinked from the consent" | `PROVIDER_ERROR` | Provided account is invalid or unlinked from the consent. | N/A | This typically occurs when an invalid account ID is included in the request, or when the account ID was unlinked from the consent due to various issues with previous requests using the same consent. | Ensure that a valid account ID is included or ask for a fresh consent from the PSU and include in the request. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "Provided account is invalid or unlinked from the consent" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------|------------------|-------------------------------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "ASPSP limit for unattended requests was exceeded" | `PROVIDER_ERROR` | The ASPSP limit for unattended requests was exceeded. | N/A | This typically occurs when the ASPSP limit (usually set to 4 requests) for unattended requests (without PSU details) is exceeded. | Please ensure that the PSU is online during AIS requests, include PSU details (isLivePsuRequest, psuIPAddress and psuAgent), or try submitting requests the following day. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "ASPSP limit for unattended requests was exceeded" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------|------------------|--------------------------------------------------------|-----------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | "ASPSP limit for unattended requests was exceeded" | `PROVIDER_ERROR` | The SCA used to access account information is expired. | N/A | This typically occurs when the existing consent has expired. | Request a new consent and retry the request. Alternatively, account details can be stored so that repeated account information requests are not required. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "New SCA required" } ] } } ```