# Get Account Information Consent source: https://developer.mastercard.com/open-banking-connect/documentation/aisfeatures/account-information-consent/index.md ## Request overview {#request-overview} The goal of this request is to send to the Account Servicing Payment Service Provider (ASPSP) the details of the Payment Service User's (PSU) consent for the Third-Party Partner (TPP) to access account information and then obtain a URI to redirect the PSU for authentication and authorization of the consent. ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| | /accounts/consents | `POST` | CMA9, Polish API, NextGenPSD2, STET, Budapest Bank, Czech Open Banking Standard API Profile, Slovak Banking API Standard API Profile | Initiates account information consent flow | The following sequence diagram shows the flow for obtaining consent. Diagram ais_consent ## Request scenario {#request-scenario} API Reference: `POST /accounts/consents` #### 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 request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | Set of elements used to define the request details | N/A | | `xRequestId` | 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}$` | | `tppRedirectURI` | URI of the TPP, where the transaction flow shall be redirected to after a Redirect | ASPSP | This element is used to specify the URI where should be redirected PSU after consent authorization | M | 1..1 | String | Call back URI where to redirect the PSU after authorization of the consent | 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 request. | ASPSP | Type of PSU request | O | 0..1 | Boolean | PSU request type | Boolean: true or false | | `psuIPAddress` | The forwarded IP address field consists of the corresponding HTTP request IP address field 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 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` | This is an internal field used for billing | MC | Used for reconciliation and clarifications | O | 0..1 | String | Identifier of the PSU in TPP system. | 1-256 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purposes | O | 0..1 | Object | 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 | | `credentials` | Send PSU credentials to ASPSP that support embedded flow | ASPSP | Include id and value for each credential required by the ASPSP. | O | 0..1 | Object | Set of elements used to define the credentials provided by PSU. Data map \<\\string, string\> | Maximum 20 value pairs. Maximum 50 symbols for each id and value. List of supported credentials can be received in response to Get List of ASPSP request. | | `validUntil` | Specified date the account permissions will expire | ASPSP | This is the date on which the account permission consent is to be expired. | O | 0..1 | String | Consent validity date (deprecated) | ISODate, YYYY-MM-DD | | `permissions` | Specifies the Open Banking account access data types. | ASPSP | This is a list of the data clusters being consented by the PSU and requested for authorization with the ASPSP. | M | 1..1 | Array | Includes the list of access permissions granted to a TPP for account information; that is, populates at least one value in the array. A mix of permission can be used, such as \[`accounts`, `balances`\] or \[`balances`, `transactions`\] but not all values together. Use \[`allPSD2`\] if to grant all permissions. | Array: \[`allPSD2`,`accounts`, `balances`, `transactions`, `standingorders`\] | | `validUntilDateTime` | Specifies date and time the account permissions will expire. | ASPSP | This is the date and time on which the account permission consent will expire. | O | 0..1 | String ISODateTime | This parameter is defining a valid until date and time for the requested consent. In case of NextGenPSD2, time is ignored and the date sent is the date when the consent will become expired. ASPSP can adjust the date of consent expiration. Please consider that ASPSPs based on STET API do not support this parameter and requests can be rejected if it is sent. | ISODateTime ISO 8601 Ex: 2017-04-05T10:43:07+00:00 | | `accounts` | List of accounts with corresponding details required by ASPSPs | ASPSP | Send a list of accounts to which the consent access is limited. | O | 0..1 | Object | Object containing a list of accounts. Only first item of the array is extracted. Multiple accounts not yet supported. Consent access is limited to the specified account. | Refer to ASPSP variations for more details on how different ASPSPs require specific account details in the request | | `accountReference` | Item from the list containing details of a certain account | ASPSP | Include the details about account. | M | 1..1 | Object | Object containing details of the account | | | `accountNumber` | Unambiguous identification of the account for which the consent access will be provided as a result of the transaction | ASPSP | Specify account in a financial institution servicing the debtor. | M | 1..1 | Object | Set of elements used to define the account details | | | `schemeName` | Name of the identification scheme, in a coded form as published in an external list. | ASPSP | This field is used to identify the type of Identification used to identify an account. | O | 0..1 | String | Account scheme name (only "IBAN" supported at the moment) | | | `identification` | Identification assigned by an institution to identify an account. This identification is known by the account owner. | ASPSP | This element is used to specify the account identification number. | O | 0..1 | String | Account identification which can be used on payload-level to address specific accounts | | | `currency` | A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". | ASPSP | The currency of the account. | O | 0..1 | String | Currency code as per ISO 4217. | | 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}$` | | `aspspSCAApproach` | Type of links admitted in this response | MC | This element is used to specify the SCA link types | O | 0..1 | Enum | Strong Customer Authentication (SCA) Approach | Enum: `REDIRECT` | | `consentRequestId` | Unique identification as assigned by the TPP to uniquely identify the consent request. | TPP | This element could be used for consent request- response tracking | O | 0..1 | String | Request consent identification | 1-256 | | `_links` | The list of link types admitted in response, (further links might be added for ASPSP defined extensions) | MC | The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request. | O | 0..1 | Object | Set of elements used to define the links details | N/A | | `scaRedirect` | In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browser | TPP | This element is used to specify the URL where the PSU should be redirected for consent authorization | O | 0..1 | URL | The URL where to redirect the PSU for authentication and authorization of the consent | | Alert: The OBIE, in alignment with the security community, recommends the use of the Hybrid flow. The platform today enforces this by setting the initial response type to **code id_token** in the authorization request to the ASPSP's Authorization Server. The Authorization server is required to return both the access code and id_token in this case, but the manner in which it does this is left to the discretion of the Authorization Server. This could be in either form: * TPP_REDIRECT_URL?All_Params * TPP_REDIRECT_URL#All_Params
The current best practice is to return these values as a hash fragment. This allows the User Agent to receive the values and skip redirection (performance enhancement), and not send the access code through a query string parameter where it will be logged by proxies, firewalls, application servers, and other services in the application path. Having the access code logged in plain text would weaken its value. For this reason, it is suggested the TPP application parse the access code from the hash fragment and POST it to the Client Service (TPP service) in an AJAX request, where the value may be safely ensconced within the POST body. An example of an URL received by TPP containing the Authorization string can be seen below. The Authorization string starts after the "#". `https://www.mastercard.com/en-us.html#code=bd9691ea-73a3-4c12-96e3-16e11680e10b&id_token=eyJhbGciOiJQUzI1NiIsImtpZCI6InprYm9LRmpRUndCZDlVRW5QQzV3bHY1N2lnNCJ9.eyJzdWIiOiJhYWMtZDBjNzJmNmQtOGQ5OS00NzVmLTg2YTYtMjUwZGI0MjkwMWNkIiwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjoiYWFjLWQwYzcyZjZkLThkOTktNDc1Zi04NmE2LTI1MGRiNDI5MDFjZCIsImlzcyI6Imh0dHBzOi8vb2IxOS1hdXRoMS11aS5vM2JhbmsuY28udWsiLCJhdWQiOiJiMzliZTYzYi03MjIyLTQyZDEtYTNkZS0yNzVjMDkwODk2ZTIiLCJpYXQiOjE2MDc2MDk2NDMsImV4cCI6MTYwNzYxMzI0Mywibm9uY2UiOiI5NWU2NjExMC1kNTdjLTRjYmEtODVkZS02YmY0OTIwNjUxM2QiLCJhdXRoX3RpbWUiOjE2MDc2MDk2NDMsImF6cCI6ImIzOWJlNjNiLTcyMjItNDJkMS1hM2RlLTI3NWMwOTA4OTZlMiIsInJlZnJlc2hfdG9rZW5fZXhwaXJlc19hdCI6MTYwNzk5ODQ0MywiY19oYXNoIjoicUM3bVZ4V2FKaWpRTVlnQ0l3RFYyQSIsInNfaGFzaCI6IkFmUUUwT1hoQUV5WFlydGpjTjMtMFEiLCJhY3IiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EifQ.NuPBxx8xQ2phh2G1DHVNgIhvA4Qf0zQSu45AR9ZzsD9pWdiAO4XCP56K2yckWNOZ15L4Kv_49Ta8AGVQANA-dcMahasq4YNDuXTP3muhQqR3A-WI8BfUtJkfG3szbINP498u61YC-CRuIPSEP1EodfLaUZPVm217XJygWp12KgfS-YApJoGdS5hjKwrvV1isxH3-skHbuvrY9f2UH78ikUz7qWD_Ux8sfmAaMw1y3AXVh193AbLq3XYeVMkUtUUFLZvUJiOZScmB36vYdy4YG7bYPeTgzFlEAkQVJstRGo3fz9VDePET3rNknY8eGYnphZ7BXH6eVcuOWSCgReAg0A&state=dG9rZW5pby1zdGF0ZQ__rq-qBaUX1N8TQX3hmAxreELWNmT3Z9-5zKtXEAq__` An edge case has been identified in which both a query string and hash fragment may be present as shown below. ![edge case](https://static.developer.mastercard.com/content/open-banking-connect/img/edge-case.png) Our suggestion to handle all situations is to develop a snippet as follows: Check for call-back URL -\> * 'Fragment' character (#) and send those parameters to the back-end for processing, ignoring 'query string' (?), if it exists. * Only if 'fragment' (#) does not exist, look for 'query string' (?) and send those parameters to the back-end. ## 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** | |-------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | N/A | `INACTIVE_URL` | The value provided for the `tppRedirectURI` parameter is invalid. Only URIs that have been registered with OBIE can be used by TPP. | n/a | Typically occurs because the TPP has not registered the URI with OBIE during onboarding. | Make sure that in order to populate the value of the `tppRedirectURI` field, you are using a URI that was registered with Open Banking Connect API as part of the onboarding details. If you think you should be able to use the specified value, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INACTIVE_URL" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------|-----------------------|------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | Permission values provided overlap or are incomplete | `INVALID_PERMISSIONS` | The values provided for the permissions set are incomplete or overlap. | "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 when: the permissions list requested does not include "accounts" when including other more granular permissions; the "allPSD2" permission is included together with other permissions; "standingorders" permission is included and "accounts" with "transactions" permissions are not present. | Make sure to request the combination of permissions that does not create any conflicts. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_PERMISSIONS", "Description": "Permission values provided overlap or are incomplete", "Details": "path[0]=/permissions" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------|-----------------|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|-------------------------------------------------------------------| | Consent expiration time cannot be in the past | `INVALID_DATE` | The value provided for consent expiration is set in the past. | "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 when TPP provides a value for consent expiration that is in the past. | Make sure to mention a date in the future for consent expiration. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_DATE", "Description": "Consent expiration time cannot be in the past", "Details": "path[0]=/validUntilDateTime" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------------------------|-----------------|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | For NextGenPSD2 ASPSPs the consent expiration day cannot be the current date | `INVALID_DAY` | The value provided for consent expiration is current day. | "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 when TPP provides in consent expiration the current date to a NextGenPSD2 ASPSP. For NextGenPSD2 ASPSPs the consent expires at the beginning of the date sent in validUntilDateTime, so consent is set to expire in the past by ASPSP. | Make sure to send a future date for consent expiration to a NextGenPSD2 ASPSP. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_DAY", "Description": "For NextGenPSD2 ASPSPs the consent expiration day cannot be the current date", "Details": "path[0]=/validUntilDateTime" } ] } } ``` | **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, etc. for each element that failed the validation | Typically occurs because the TPP has provided in request `isLivePsuRequest`=true and didn't 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** | |--------------------------------------------------|------------------|------------------------------------------------------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | Setting consent expiration not supported by bank | `PROVIDER_ERROR` | Consent expiration parameter is not supported by some ASPSPs in Account Information Consent request. | N/A | Occurs when consent expiration parameter (validUntilDateTime) is not supported in Account Information Consent request. | Resubmit Account Information Consent request without validUntilDateTime data. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Setting consent expiration not supported by bank" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------------------------|------------------|------------------------------------------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Short-lived consent must be submitted before the long-lived one | `PROVIDER_ERROR` | Short-lived consent must be submitted before the long-lived one. | N/A | Occurs when Erste Refresh solution is used, and a consent with validUntilDateTime\>24 hours from current time is requested, without having an active consent with validUntilDateTime\<24 hours from current time. | Please ensure that a valid consent with validUntilDateTime\<24 hours from current time is available, before submitting a consent with validUntilDateTime\>24 hours. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "Short-lived consent must be submitted before the long-lived one" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------|------------------|------------------------------------------------------------------|-----------------------|---------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Missing mandatory details | `PROVIDER_ERROR` | Mandatory details required by ASPSPs are missing in the request. | N/A | Occurs when specific fields required by some ASPSPs were not included in the request. | Please check the response to Get List of ASPSPs request and information on Mastercard Developer Portal to check the list of mandatory fields required by specific ASPSPs, and resubmit the request with mandatory field(s), | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "Missing mandatory details" } ] } } ```