...
The Account and Transaction API Profile describes the flows and common functionality functionalities for the Accounts and Transaction API, which allows an Account Information Service Provider ('AISP') to:
...
Alternative Flows: Documents rules for alternative flows.
2.2 Resources
Each of the Account and Transaction API resources are documented in the Resources and Data Models / AISP area of the specification. Each resource is documented with:
Endpoints
The API endpoints available for the resource
Data Model
Resource definition
UML diagram
Permissions as they relate to accessing the resource
Data dictionary - which defines fields, re-usable classes, mandatory (1..1) or conditional (0..1) as defined in the Design Principles section, and enumerations.
Usage Examples
3. Basics
3.1 Overview
...
This flow begins with a user/customer consenting to allow an AISP to access account information data
Step 2: Setup Account-Access Consent-Consents
The AISP connects to the ASPSP that services the useruser’s/customer’s account(s) and creates an account-access-consentconsents resource. This informs the ASPSP that one of its userusers/customers is granting access to account and transaction information to an AISP. The ASPSP responds with an identifier for the resource (the ConsentId - which is the intent identifier). This step is carried out by making a POST request to / account-access-consents endpoint
The account-access-consent resource sresource will include these fields below - which describe the data that the user/customer has consented with the AISP:
Permissions - a list of data clusters that have been consented for access
Transaction Validity Period - the From/To date range which specifies a historical period for transactions and statements which may be accessed by the AISP
...
The AISP requests the user/customer to authorise the consent. The ASPSP may carry this out by using a redirection flow or a decoupled flow
In a redirection flow, the AISP redirects the user/customer to the ASPSP
The redirect includes the ConsentId generated in the previous step
This allows the ASPSP to correlate the account-access-consent consents that was setup
The ASPSP authenticates the user/customer
The ASPSP updates the state of the account-access-consent consents resource internally to indicate that the account-access consent -consents has been authorised
Once the consent has been authorised, the user/customer is redirected back to the AISP
In a decoupled flow, the ASPSP requests the user/customer to authorise consent on an authentication device that is separate from the consumption device on which the user/customer is interacting with the AISP
The decoupled flow is initiated by the AISP calling a back-channel authorisation request
The request contains a 'hint' that identifies the user/customer, paired with the consent to be authorised
The ASPSP authenticates the user/customer and updates the state of the account-access-consent consents resource internally to indicate that the account-access consent -consents has been authorised
Once the consent has been authorised, the ASPSP can make a callback to the AISP to provide an access token
The consent is managed between the user/customer and the AISP - so the account-access-consent consents details must not be changed (with the ASPSP) in this step. The user/customer will only be able to authorise or reject the account-access-consent consents details in its entirety
During authorisation, the user/customer selects accounts that are authorised for the AISP request (in the ASPSP’s banking interface)
...
This is carried out by making a GET request the relevant resource
The unique AccountId(s) that are valid for the account-access-consent consents will be returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token
...
The API endpoints for creating account-access-consent consents resources are not idempotent.
If a time-out error occurs - then an AISP can create a new account-access-consent consents resource - rather than try with the same resource.
...
An AISP must not create a Consent on a newer version, and use it on a previous version
E.g., A ConsentId for an account-access-consent consents created in v3, must not be used to access v2 endpoints
...
An AISP must not access a Consent on an older version, via the Id for a Consent created in a newer version:
E.g., An account-access-consent consents created in v3 accessed via v2 account-request
An ASPSP must allow a Consent to be accessed in a newer version
An ASPSP must ensure Permissions set associated with a Consent are unchanged when accessed in a different version:
E.g., An account-request created in v2 will have the same details when accessed via v2 and v3 (as an account-access-consentconsents)
An ASPSP must ensure a Consent's fields are unchanged when accessed in a different version
An ASPSP may allow expired Consents to be accessed in a newer version
An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all (if not mandatory):
E.g., OBAccountAccessConsentResponse /Data/StatusUpdateDateTime introduced in v2 accessed with v1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records
...
An AISP must not patch a Consent on an older version, via an Id for a Consent created in a newer version:
E.g., An account-access-consent consents is created in v3, and request PATCH on v2
An ASPSP must support patching a Consent from a previous version via a newer version:
E.g., An account-request is created in v2, and request PATCH on v3
...
An AISP may use a token that is bound to a Consent in a previous version, to access an endpoint of a newer version.
An AISP may use an Id for a Consent created in a previous version to retrieve Account Information resources in a newer version:
E.g., AccountRequestId from v2 can be used as ConsentId in v3, to GET /accounts
An AISP must not use an Id for a Consent from a newer version to access Account Information resources in a previous version:
E.g., ConsentId for an account-access-consent consents created in v3, must not be used to access v2 Account Information endpoints.
An ASPSP must allow an AISP to use an Id for a Consent from a previous version to access Account Information resource endpoints in a newer version:
E.g., AccountRequestId created in v2 must be allowed to access Account Information resource endpoints in v3.
An ASPSP must reject the request to access a resource, for which a Consent's Permissions set does not permit.
An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all:
E.g., OBAccountAccessConsentResponse /Data/StatusUpdateDateTime introduced in Version2 accessed with V1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records.
4.Security & Access Control
...
The AISP must create an account-access-consentconsents resource through a POST operation. This resource indicates the consent that the AISP claims it has been given by the user/customer to retrieve account and transaction information. At this stage, the consent is not yet authorised as the ASPSP has not yet verified this claim with the user/customer.
...
4.3.1 Consent Elements
The Account Access Consent -access-consents resource consists of the following fields, which together form the elements of the consent provided by the user/customer to the AISP:
...
Permissions | Endpoints | Business Logic | Data Cluster Description |
ReadAccountsBasic | /accounts |
| Ability to read basic account information |
ReadAccountsDetail | /accounts | Access to additional elements in the payload | Ability to read account identification details |
ReadBalances | /balances |
| Ability to read all balance information |
ReadBeneficiariesBasic | /beneficiaries |
| Ability to read basic beneficiary details |
ReadBeneficiariesDetail | /beneficiaries | Access to additional elements in the payload | Ability to read account identification details for the beneficiary |
ReadDirectDebits | /direct-debits |
| Ability to read all direct debit information |
ReadTransactionsBasic | /transactions | Permissions must also include at least one of:
| Ability to read basic transaction information |
ReadTransactionsDetail | /transactions | Access to additional elements in the payload Permissions must also include at least one of:
| Ability to read transaction data elements which may hold silent party details |
ReadTransactionsCredits | /transactions | Access to credit transactions. Permissions must also include one of:
| Ability to read only credit transactions |
ReadTransactionsDebits | /transactions | Access to debit transactions. Permissions must also include one of:
| Ability to read only debit transactions |
ReadStatementsBasic | /statements |
| Ability to read basic statement details |
ReadStatementsDetail | /statements | Access to additional elements in the payload Access to download the statement file (if the ASPSP makes this available). | Ability to read statement data elements which may leak other information about the account |
ReadSupplementaryAccountInfo | /supplementary-account-info |
| Ability to read all product information relating to the account |
ReadOffers | /offers |
| Ability to read all offer information |
ReadParty | /accounts/{AccountId}/party |
| Ability to read party information on the account owner |
ReadPartyCustomer | /party |
| Ability to read party information on the user/customer logged in |
ReadFutureDatedPaymentsBasic | /future-dated-payments |
| Ability to read basic statement details |
ReadFutureDatedPaymentsDetail | /future-dated-payments | Access to additional elements in the payload |
|
ReadPAN | All API endpoints where PAN is available as a structured field | Request to access to PAN in the clear | Request to access PAN in the clear across the available endpoints. If this permission code is not in the account-access-consentconsents, the AISP will receive a masked PAN. While an AISP may request to access PAN in the clear, an ASPSP may still respond with a masked PAN if:
|
...
All other fields (other than these fields listed) are available with the "Basic" Permission access.
Permission - Detail Codes | Data Element Name | Occurrence | XPath |
ReadAccountsDetail | Account | 0..1 | OBReadAccount/Data/Account/Account |
ReadAccountsDetail | Servicer | 0..1 | OBReadAccount/Data/Account/Servicer |
ReadBeneficiariesDetail | CreditorAgent | 0..1 | OBReadBeneficiary/Data/Beneficiary/CreditorAgent |
ReadBeneficiariesDetail | CreditorAccount | 0..1 | OBReadBeneficiary/Data/Beneficiary/CreditorAccount |
ReadStandingOrdersDetail | CreditorAgent | 0..1 | OBReadStandingOrder/Data/StandingOrder/CreditorAgent |
ReadStandingOrdersDetail | CreditorAccount | 0..1 | OBReadStandingOrder/Data/StandingOrder/CreditorAccount |
ReadTransactionsDetail | TransactionInformation | 0..1 | OBReadTransaction/Data/Transaction/TransactionInformation |
ReadTransactionsDetail | Balance | 0..1 | OBReadTransaction/Data/Transaction/Balance |
ReadTransactionsDetail | MerchantDetails | 0..1 | OBReadTransaction/Data/Transaction/MerchantDetails |
ReadTransactionsDetail | CreditorAgent | 0..1 | OBReadTransaction/Data/Transaction/CreditorAgent |
ReadTransactionsDetail | CreditorAccount | 0..1 | OBReadTransaction/Data/Transaction/CreditorAccount |
ReadTransactionsDetail | DebtorAgent | 0..1 | OBReadTransaction/Data/Transaction/DebtorAgent |
ReadTransactionsDetail | DebtorAccount | 0..1 | OBReadTransaction/Data/Transaction/DebtorAccount |
ReadStatementsDetail | StatementAmount | 0..n | OBReadStatement/Data/Statement/StatementAmount |
ReadFutureDatedPaymentsDetail | CreditorAgent | 0..1 | OBReadFutureDatedPayment/Data/FutureDatedPayment/CreditorAgent |
ReadFutureDatedPaymentsDetail | CreditorAccount | 0..1 | OBReadFutureDatedPayment/Data/FutureDatedPayment/CreditorAccount |
...
S. No. | Status | Description |
1 | Authorised | The account-access consent -consents has been successfully authorised. |
2 | Rejected | The account-access consent -consents has been rejected. |
3 | Revoked | The account-access consent -consents has been revoked via the AISP interface. |
...
A user/customer can re-authenticate an Account Access Consent account-access-consents if:
The account-access-consent has a status of Authorised
...
An AISP and User/Customer may have multiple consents at any point in time.
4.4 Consent Revocation
A user/customer may revoke consent for accessing account information at any point in time.
...
The AISP must cease to access the APIs at that point
The AISP must call the PATCH operation on the account-access-consent consents resource (before confirming consent revocation with the user/customer) as soon as is practically possible, to indicate to the ASPSP that the user/customer has revoked
...
The ASPSPs must revoke the access token provided to the AISP
The status of the account-access-consent must remain consents must remain unchanged and the AISP must be allowed to request user/customer to re-authenticate the same account-access-consent consents resource
Upon successful re-authentication by user/customer, an ASPSP may issue new authorisation code and subsequently new access token to the AISP
4.6 Changes to Selected Account(s)
The user/customer must select customer must select the accounts to which the consent should be applied at the point of consent authorisation.
...
The account being closed
The account is barred or frozen
The beneficial owner of the account revokes the useruser’s/customer's mandate or power of attorney to operate the account
...
Code Class | Name | Definition |
OBAccountStatusCode | Enabled | Account can be used for its intended purpose. |
OBAccountStatusCode | Disabled | Account cannot be used for its intended purpose, either temporarily or permanently. |
OBAccountStatusCode | Deleted | Account cannot be used any longer. |
OBAccountStatusCode | ProForma | Account is temporary and can be partially used for its intended purpose. The account will be fully available for use when the account servicer has received all relevant documents. |
OBAccountStatusCode | Pending | Account change is pending approval. |
OBAddressTypeCode | Business | Address is the business address. |
OBAddressTypeCode | Correspondence | Address is the address where correspondence is sent. |
OBAddressTypeCode | DeliveryTo | Address is the address to which delivery is to take place. |
OBAddressTypeCode | MailTo | Address is the address to which mail is sent. |
OBAddressTypeCode | POBox | Address is a postal office (PO) box. |
OBAddressTypeCode | Postal | Address is the complete postal address. |
OBAddressTypeCode | Residential | Address is the home address. |
OBAddressTypeCode | Statement | Address is the address where statements are sent. |
OBBalanceTypeCode | ClosingAvailable | Closing balance of amount of money that is at the disposal of the account owner on the date specified. |
OBBalanceTypeCode | ClosingBooked | Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. |
OBBalanceTypeCode | ClosingCleared | Closing balance of amount of money that is cleared on the date specified. |
OBBalanceTypeCode | Expected | Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. |
OBBalanceTypeCode | ForwardAvailable | Forward available balance of money that is at the disposal of the account owner on the date specified. |
OBBalanceTypeCode | Information | Balance for informational purposes. |
OBBalanceTypeCode | InterimAvailable | Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
OBBalanceTypeCode | InterimBooked | Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
OBBalanceTypeCode | InterimCleared | Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. |
OBBalanceTypeCode | OpeningAvailable | Opening balance of amount of money that is at the disposal of the account owner on the date specified. |
OBBalanceTypeCode | OpeningBooked | Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. |
OBBalanceTypeCode | OpeningCleared | Opening balance of amount of money that is cleared on the date specified. |
OBBalanceTypeCode | PreviouslyClosedBooked | Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. |
OBCreditDebitCode | Credit | Operation is a credit |
OBCreditDebitCode | Debit | Operation is a debit |
OBEntryStatusCode | Booked | Booked means that the transfer of money has been completed between account servicer and account owner. Usage: Status Booked does not necessarily imply finality of money as this depends on other factors such as the payment system used, the completion of the end- to-end transaction and the terms agreed between account servicer and owner. Status Booked is the only status that can be reversed. |
OBEntryStatusCode | Pending | Booking on the account owner's account in the account servicer's ledger has not been completed. Usage: this can be used for expected items, or for items for which some conditions still need to be fulfilled before they can be booked. If booking takes place, the entry will be included with status Booked in subsequent account report or statement. Status Pending cannot be reversed. |
OBEntryStatusCode | Interimpending | Booking on the account owner’s account is complete but may be reversed due to other factors such as payment system failure, non completion of end-to-end transaction, etc. |
OBExternalAccountSubTypeCode | ChargeCard | Account sub-type is a Charge Card. |
OBExternalAccountSubTypeCode | CreditCard | Account sub-type is a Credit Card. |
OBExternalAccountSubTypeCode | CurrentAccount | Account sub-type is a Current Account. |
OBExternalAccountSubTypeCode | EWallet | Account sub-type is an EWalletE-Wallet |
OBExternalAccountSubTypeCode | Loan | Account sub-type is a Loan. |
OBExternalAccountSubTypeCode | Mortgage | Account sub-type is a Mortgage. |
OBExternalAccountSubTypeCode | PrePaidCard | Account sub-type is a PrePaid Card. |
OBExternalAccountSubTypeCode | Savings | Account sub-type is a Savings. |
OBExternalAccountSubTypeCode | Deposit | Account sub-type is a Deposit/Investment account. |
OBExternalAccountTypeCode | Business | Account type is for business. |
OBExternalAccountTypeCode | Personal | Account type is for personal. |
OBExternalCardAuthorisationTypeCode | ConsumerDevice | Card authorisation was via a Consumer Device Cardholder Verification Method (CDCVM) |
OBExternalCardAuthorisationTypeCode | Contactless | Card authorisation was via Contactless. |
OBExternalCardAuthorisationTypeCode | None | No card authorisation was used. |
OBExternalCardAuthorisationTypeCode | PIN | Card authorisation was via PIN. |
OBExternalCardSchemeTypeCode | AmericanExpress | AmericanExpress scheme. |
OBExternalCardSchemeTypeCode | Diners | Diners scheme. |
OBExternalCardSchemeTypeCode | JCB | JCB scheme. |
OBExternalCardSchemeTypeCode | MasterCard | MasterCard scheme. |
OBExternalCardSchemeTypeCode | VISA | VISA scheme. |
OBExternalLimitTypeCode | Available | The amount of credit limit available to the account holder |
OBExternalLimitTypeCode | Credit | The amount of a credit limit that has been agreed with the account holder |
OBExternalLimitTypeCode | Emergency | The amount of an arranged lending limit that can be borrowed on top of pre-agreed lending, that has been agreed with the account holder |
OBExternalLimitTypeCode | Pre-Agreed | The amount of an arranged lending limit that has been agreed with the account holder |
OBExternalLimitTypeCode | Temporary | The amount of a temporary lending limit that has been agreed with the account holder |
OBExternalOfferTypeCode | BalanceTransfer | Offer is a balance transfer. |
OBExternalOfferTypeCode | LimitIncrease | Offer is a limit increase. |
OBExternalOfferTypeCode | MoneyTransfer | Offer is a money transfer. |
OBExternalOfferTypeCode | Other | Offer is of other type. |
OBExternalOfferTypeCode | PromotionalRate | Offer is a promotional rate. |
OBExternalPartyTypeCode | Delegate | Party that has delegated access. |
OBExternalPartyTypeCode | Joint | Party is a joint owner of the account. |
OBExternalPartyTypeCode | Sole | Party is a sole owner of the account. |
OBExternalFutureDateTypeCode | Arrival | Future Dated payment date is specified as the arrival date for the recipient |
OBExternalFutureDateTypeCode | Execution | Future Dated payment date is specified as the execution date |
OBExternalStandingOrderStatusCode | Active | The standing order is active. |
OBExternalStandingOrderStatusCode | Inactive | The standing order is inactive. |
OBExternalStatementTypeCode | AccountClosure | Final account closure statement. |
OBExternalStatementTypeCode | AccountOpening | First statement provided for an account. |
OBExternalStatementTypeCode | Annual | Annual statement report. |
OBExternalStatementTypeCode | Interim | Adhoc or customised statement period. |
OBExternalStatementTypeCode | RegularPeriodic | Regular pre-agreed reporting statement. |
5.2.2 ISO Enumerations
These following ISO Enumerations are used in the Account APIs.
...