Version | Date | Author | Comments |
---|---|---|---|
3.0 | OB R/W API Team | This is the baseline version. No change from RC3. Swagger URLs have been updated to point to the latest stable version. | |
3.1-draft1 | OB R/W API Team | This is the initial draft version for 3.1. Errata
| |
3.1-draft2 | OB R/W API Team | No Change | |
3.1-draft3 | OB R/W API Team | Draft 3 Changes:
| |
3.1-draft4 | OB R/W API Team | Draft 4 Changes:
| |
3.1-RC1 | OB R/W API Team | RC1 Changes:
| |
3.1 | OB R/W API Team | Version 3.1 final release. No changes from Version 3.1 RC1. Swagger updated to latest release candidate |
This specification describes the Account Information and Transaction API flows and payloads.
The API endpoints described here allow an Account Information Service Provider ('AISP') to:
This specification should be read in conjunction with Read/Write Data API Specification which provides a description of the elements that are common across all the Read/Write Data APIs.
This document consists of the following parts:
Overview: Provides an overview of the API and the key decisions and principles that contributed to the specification.
Basics: Identifies the resources, operations that are permitted on those resources, and various special cases.
Endpoints: Provides the list of endpoints for the API specification. The individual end-points are documented in separate pages along with the data model that they employ and usage examples.
Security & Access Control: Specifies the means for AISPs and PSUs to authenticate themselves and provide consent.
Data & Payloads: Documents data structures and data architecture that applies to all the end-points. End-point specific data structures are documented in separate pages along with the end-points that employ the data structure.
Swagger Specifications: Provides links to the swagger specifications for the APIs.
The figure below provides a general outline of an account information request and flow using the Account Info APIs.
Step 1: Request Account Information
Step 2: Setup Account Access Consent
Step 3: Authorise Consent
Step 4: Request Data
participant PSU participant AISP participant ASPSP Authorisation Server participant ASPSP Resource Server note over PSU, ASPSP Resource Server Step 1: Request account information end note PSU -> AISP: Get account/transaction information note over PSU, ASPSP Resource Server Step 2: Setup account access consent end note AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA AISP -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server -> AISP: access-token AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA AISP -> ASPSP Resource Server: POST /account-access-consents state over ASPSP Resource Server: Consent Status: AwaitingAuthorisation ASPSP Resource Server -> AISP: HTTP 201 (Created), ConsentId note over PSU, ASPSP Resource Server Step 3: Authorise consent end note alt Redirection (Using Authorization Code Grant) AISP -> PSU: HTTP 302 (Found), Redirect (ConsentId) PSU -> ASPSP Authorisation Server: Follow redirect (ConsentId) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: select accounts state over ASPSP Resource Server: Consent Status: Authorised ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (authorization-code) PSU -> AISP: Follow redirect (authorization-code) AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA AISP -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> AISP: access-token else Decoupled (Using CIBA) AISP -> ASPSP Authorisation Server: POST /bc-authorize (login_hint_token) ASPSP Authorisation Server -> AISP: OK PSU -> ASPSP Authorisation Server: Authorise (Consent Id) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: select accounts state over ASPSP Resource Server: Consent Status: Authorised alt Using callback ASPSP Authorisation Server -> AISP: Callback (authorization-code) AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA AISP -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> AISP: access-token else Using polling AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA AISP -> ASPSP Authorisation Server: Poll at /token using auth-req-id ASPSP Authorisation Server -> AISP: access-token end alt end alt note over PSU, ASPSP Resource Server Step 4: Request data end note AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA AISP -> ASPSP Resource Server: GET /accounts ASPSP Resource Server -> AISP: HTTP 200 (OK), List of accounts containing AccountId(s) AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions ASPSP Resource Server -> AISP: HTTP 200 (OK), List of transactions option footer=bar |
The API endpoints for creating account-access-consent resources are not idempotent.
If a time-out error occurs - then we would expect an AISP to create a new account-access-consent resource - rather than try with the same resource.
This section overviews the release management and versioning strategy for the Account and Transaction API.
The account-access-consent resource is referred to as an account-request resource in v1 and v2 of this specification. For clarity, it has been generalised to 'Consent' in the detail below.
This section looks at the list of available API endpoints to access Account Information and Transaction data and optionality (definitions of mandatory, conditional or optional are defined in the Principles section).
Endpoint design considerations:
We have specified the "mandatory" endpoints for the functioning of the Account Info APIs.
However, endpoints will not be "mandatory" if ASPSPs do not provide these resources via existing online channels e.g., direct debits, standing orders, statements.
The access tokens required for accessing the Account Info APIs must have at least the following scope:
accounts |
AISPs must use a client credentials grant to obtain a token to access the account-access-consents resource. In the specification, this grant type is referred to as "Client Credentials".
AISPs must use an authorization code grant using a redirect or decoupled flow to obtain a token to access all other resources. In the specification, this grant type is referred to as "Authorization Code".
The AISP must create an account-access-consent resource through a POST operation. This resource indicates the consent that the AISP claims it has been given by the PSU 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 PSU.
The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).
As part of the consent authorization flow:
Once these steps are complete, the consent is considered to have been authorised by the PSU.
The Account Access Consent resource consists of the following fields, which together form the elements of the consent provided by the PSU to the AISP:
Permissions codes will be used to limit the data that is returned in response to a resource request.
When a permission is granted for a "Detail" permission code (e.g., ReadAccountsDetail) it implies that access is also granted to the corresponding "Basic" permission code (e.g., ReadAccountsBasic).
While it is duplication for a TPP to request a "Basic" permission code and the corresponding "Detail" permission code, it is not a malformed request, and the ASPSP must not reject solely on the basis of duplication.
The permissions array must contain at least ReadAccountsBasic or ReadAccountsDetail.
The following combinations of permissions are not allowed, and the ASPSP must reject these account-access-consents with a 400 response code:
Permissions | Endpoints | Business Logic | Data Cluster Description |
---|---|---|---|
ReadAccountsBasic | /accounts /accounts/{AccountId} | Ability to read basic account information | |
ReadAccountsDetail | /accounts /accounts/{AccountId} | Access to additional elements in the payload | Ability to read account identification details |
ReadBalances | /balances /accounts/{AccountId}/balances | Ability to read all balance information | |
ReadBeneficiariesBasic | /beneficiaries /accounts/{AccountId}/beneficiaries | Ability to read basic beneficiary details | |
ReadBeneficiariesDetail | /beneficiaries /accounts/{AccountId}/beneficiaries | Access to additional elements in the payload | Ability to read account identification details for the beneficiary |
ReadDirectDebits | /direct-debits /accounts/{AccountId}/direct-debits | Ability to read all direct debit information | |
ReadStandingOrdersBasic | /standing-orders /accounts/{AccountId}/standing-orders | Ability to read basic standing order information | |
ReadStandingOrdersDetail | /standing-orders /accounts/{AccountId}/standing-orders | Access to additional elements in the payload | Ability to read account identification details for beneficiary of the standing order |
ReadTransactionsBasic | /transactions /accounts/{AccountId}/transactions /accounts/{AccountId}/statements/{StatementId}/transactions | Permissions must also include at least one of:
| Ability to read basic transaction information |
ReadTransactionsDetail | /transactions /accounts/{AccountId}/transactions /accounts/{AccountId}/statements/{StatementId}/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 /accounts/{AccountId}/transactions /accounts/{AccountId}/statements/{StatementId}/transactions | Access to credit transactions. Permissions must also include one of:
| Ability to read only credit transactions |
ReadTransactionsDebits | /transactions /accounts/{AccountId}/transactions /accounts/{AccountId}/statements/{StatementId}/transactions | Access to debit transactions. Permissions must also include one of:
| Ability to read only debit transactions |
ReadStatementsBasic | /statements /accounts/{AccountId}/statements | Ability to read basic statement details | |
ReadStatementsDetail | /statements /accounts/{AccountId}/statements /accounts/{AccountId}/statements/{StatementId}/file | 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 |
ReadProducts | /products /accounts/{AccountId}/product | Ability to read all product information relating to the account | |
ReadOffers | /offers /accounts/{AccountId}/offers | Ability to read all offer information | |
ReadParty | /accounts/{AccountId}/party | Ability to read party information on the account owner. | |
ReadPartyPSU | /party | Ability to read party information on the PSU logged in. | |
ReadScheduledPaymentsBasic | /scheduled-payments /accounts/{AccountId}/scheduled-payments | Ability to read basic statement details | |
ReadScheduledPaymentsDetail | /scheduled-payments /accounts/{AccountId}/scheduled-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-consent, 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:
|
The additional elements that are granted for "Detail" permissions are listed in this section.
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 | OBReadAccount3/Data/Account/Account |
ReadAccountsDetail | Servicer | 0..1 | OBReadAccount3/Data/Account/Servicer |
ReadBeneficiariesDetail | CreditorAgent | 0..1 | OBReadBeneficiary3/Data/Beneficiary/CreditorAgent |
ReadBeneficiariesDetail | CreditorAccount | 0..1 | OBReadBeneficiary3/Data/Beneficiary/CreditorAccount |
ReadStandingOrdersDetail | CreditorAgent | 0..1 | OBReadStandingOrder4/Data/StandingOrder/CreditorAgent |
ReadStandingOrdersDetail | CreditorAccount | 0..1 | OBReadStandingOrder4/Data/StandingOrder/CreditorAccount |
ReadTransactionsDetail | TransactionInformation | 0..1 | OBReadTransaction4/Data/Transaction/TransactionInformation |
ReadTransactionsDetail | Balance | 0..1 | OBReadTransaction4/Data/Transaction/Balance |
ReadTransactionsDetail | MerchantDetails | 0..1 | OBReadTransaction4/Data/Transaction/MerchantDetails |
ReadTransactionsDetail | CreditorAgent | 0..1 | OBReadTransaction4/Data/Transaction/CreditorAgent |
ReadTransactionsDetail | CreditorAccount | 0..1 | OBReadTransaction4/Data/Transaction/CreditorAccount |
ReadTransactionsDetail | DebtorAgent | 0..1 | OBReadTransaction4/Data/Transaction/DebtorAgent |
ReadTransactionsDetail | DebtorAccount | 0..1 | OBReadTransaction4/Data/Transaction/DebtorAccount |
ReadStatementsDetail | StatementAmount | 0..* | OBReadStatement1/Data/Statement/StatementAmount |
ReadScheduledPaymentsDetail | CreditorAgent | 0..1 | OBReadScheduledPayment2/Data/ScheduledPayment/CreditorAgent |
ReadScheduledPaymentsDetail | CreditorAccount | 0..1 | OBReadScheduledPayment2/Data/ScheduledPayment/CreditorAccount |
In addition the ReadStatementsDetail is required to access the statement file download via: /accounts/{AccountId}/statements/{StatementId}/file
Example behaviour of the Permissions for the ReadAccountsBasic and ReadAccountsDetail codes is as follows:
It is expected that transactions will be returned in the payload irrespective of whether they are reversing entries, as long as the PSU has provided consent for that type of transaction.
If the PSU has provided permission for ReadTransactionsCredits, the ASPSP must include all credits, including debit reversals.
If the PSU has provided permission for ReadTransactionsDebits, the ASPSP must include all debits, including credit reversals.
The ExpirationDateTime is an optional field which specifies the expiration for AISP access to the PSU's data.
The field is optional as the consent for AISP access to a PSU's data may be indefinite. The ExpirationDateTime is different from the RTS requirement for a PSU to re-authenticate after 90 days. The same account-access-consent resource will be re-authenticated with the same ExpirationDateTime as the original request.
The ExpirationDateTime applies to all Permissions (data clusters) being consented.
The TransactionToDateTime and the TransactionFromDateTime specify the period for consented transaction and/or statement history. Both the fields are optional and one may be specified without the other.
The AISP must be restricted to accessing transactions within this period when accessing the transactions resource.
The AISP must be restricted to accessing statements which are completely within this period when accessing the statements resource.
The Account Access Consent resource may have one of the following status codes after authorisation has taken place:
Status | Description | |
---|---|---|
1 | Authorised | The account access consent has been successfully authorised. |
2 | Rejected | The account access consent has been rejected. |
3 | Revoked | The account access consent has been revoked via the ASPSP interface. |
Account Access Consents are long-lived consents.
A PSU can re-authenticate an Account Access Consent if:
Authorised
and ExpirationDateTime
of the account-access-consent, if specified, has not elapsed.The accounts bound to the account-access-consent are selected in the ASPSP domain.
An ASPSP may allow the PSU to change the selected accounts during consent re-authentication.
A PSU may revoke consent for accessing account information at any point in time.
A PSU may revoke authorisation directly with the ASPSP. The mechanisms for this are in the competitive space and are up to each ASPSP to implement in the ASPSP's banking interface. If the PSU revokes authorisation with the ASPSP, the Status of the account-access-consent resource must be set to Revoked.
The PSU may request the AISP to revoke consent that it has authorised. If consent is revoked with the AISP:
The PSU must select the accounts to which the consent should be applied at the point of consent authorisation.
Subsequent changes to the set of accounts to which the consent authorisation applies may be carried out directly with the ASPSP. The method for doing this lies in the competitive space and is not part of this specification.
Additionally, the set of selected accounts may also change due to external factors. This includes (but is not limited to):
In these scenarios, only the affected account is removed from the list of selected accounts. The ASPSP must not revoke authorisation to other accounts.
Information for risk scoring and assessment will come via:
No fields for business logic security concerns have been identified for the Account Info APIs.
For Accounts & Transaction APIs, the Meta
section in API responses may contain two additional fields to indicate the date range for which data has been returned.
The transactions or statements for a particular range of dates may be excluded from the response because:
The absence of transactions / statements in the payload does not indicate that there were no transactions / statements during that period.
To ensure that the data is interpreted correctly, the ASPSP may provide the date of the first available transaction and last available transaction as part of the response in the Meta section in the FirstAvailableDateTime and LastAvailableDateTime fields.
"Meta": { "TotalPages": 1, "FirstAvailableDateTime": "2017-05-03T00:00:00+00:00", "LastAvailableDateTime": "2017-12-03T00:00:00+00:00" } |
The Account Info API resources, where possible, have been borrowed from the ISO 20022 camt.052 XML standard. However, has been adapted for APIs based as per our design principles.
Deviations from the camt.052 XML standard are:
Variations for the transactions structure include:
Renaming "entry" to "transaction" for consistency as this is the language used in the CMA Order and PSD2.
DateTime elements used instead of a complex choice of Date and DateTime.
Flattening of the structure for BankTransactionCode and ProprietaryBankTransactionCode.
Additional information for an AddressLine, MerchantDetails and a running Balance.
Each of the Account and Transaction API resources are documented in sub-pages of this specification. Each resource is documented with:
Code Class | Name | Definition |
---|---|---|
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. |
OBBalanceType1Code | ClosingAvailable | Closing balance of amount of money that is at the disposal of the account owner on the date specified. |
OBBalanceType1Code | 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. |
OBBalanceType1Code | ClosingCleared | Closing balance of amount of money that is cleared on the date specified. |
OBBalanceType1Code | 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. |
OBBalanceType1Code | ForwardAvailable | Forward available balance of money that is at the disposal of the account owner on the date specified. |
OBBalanceType1Code | Information | Balance for informational purposes. |
OBBalanceType1Code | 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. |
OBBalanceType1Code | 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. |
OBBalanceType1Code | 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. |
OBBalanceType1Code | OpeningAvailable | Opening balance of amount of money that is at the disposal of the account owner on the date specified. |
OBBalanceType1Code | 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. |
OBBalanceType1Code | OpeningCleared | Opening balance of amount of money that is cleared on the date specified. |
OBBalanceType1Code | 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 |
OBEntryStatus1Code | 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. |
OBEntryStatus1Code | 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. |
OBExternalAccountSubType1Code | ChargeCard | Account sub-type is a Charge Card. |
OBExternalAccountSubType1Code | CreditCard | Account sub-type is a Credit Card. |
OBExternalAccountSubType1Code | CurrentAccount | Account sub-type is a Current Account. |
OBExternalAccountSubType1Code | EMoney | Account sub-type is an EMoney. |
OBExternalAccountSubType1Code | Loan | Account sub-type is a Loan. |
OBExternalAccountSubType1Code | Mortgage | Account sub-type is a Mortgage. |
OBExternalAccountSubType1Code | PrePaidCard | Account sub-type is a PrePaid Card. |
OBExternalAccountSubType1Code | Savings | Account sub-type is a Savings. |
OBExternalAccountType1Code | Business | Account type is for business. |
OBExternalAccountType1Code | Personal | Account type is for personal. |
OBExternalCardAuthorisationType1Code | ConsumerDevice | Card authorisation was via a Consumer Device Cardholder Verification Method (CDCVM). |
OBExternalCardAuthorisationType1Code | Contactless | Card authorisation was via Contactless. |
OBExternalCardAuthorisationType1Code | None | No card authorisation was used. |
OBExternalCardAuthorisationType1Code | PIN | Card authorisation was via PIN. |
OBExternalCardSchemeType1Code | AmericanExpress | AmericanExpress scheme. |
OBExternalCardSchemeType1Code | Diners | Diners scheme. |
OBExternalCardSchemeType1Code | Discover | Discover scheme. |
OBExternalCardSchemeType1Code | MasterCard | MasterCard scheme. |
OBExternalCardSchemeType1Code | VISA | VISA scheme. |
OBExternalLimitType1Code | Available | The amount of credit limit available to the account holder |
OBExternalLimitType1Code | Credit | The amount of a credit limit that has been agreed with the account holder |
OBExternalLimitType1Code | 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 |
OBExternalLimitType1Code | Pre-Agreed | The amount of an arranged lending limit that has been agreed with the account holder |
OBExternalLimitType1Code | Temporary | The amount of a temporary lending limit that has been agreed with the account holder |
OBExternalOfferType1Code | BalanceTransfer | Offer is a balance transfer. |
OBExternalOfferType1Code | LimitIncrease | Offer is a limit increase. |
OBExternalOfferType1Code | MoneyTransfer | Offer is a money transfer. |
OBExternalOfferType1Code | Other | Offer is of an other type. |
OBExternalOfferType1Code | PromotionalRate | Offer is a promotional rate. |
OBExternalPartyType1Code | Delegate | Party that has delegated access. |
OBExternalPartyType1Code | Joint | Party is a joint owner of the account. |
OBExternalPartyType1Code | Sole | Party is a sole owner of the account. |
OBExternalScheduleType1Code | Arrival | Scheduled payment date is specified as the arrival date for the recipient. |
OBExternalScheduleType1Code | Execution | Scheduled payment date is specified as the execution date. |
OBExternalStandingOrderStatus1Code | Active | The standing order is active. |
OBExternalStandingOrderStatus1Code | Inactive | The standing order is inactive. |
OBExternalStatementType1Code | AccountClosure | Final account closure statement. |
OBExternalStatementType1Code | AccountOpening | First statement provided for an account. |
OBExternalStatementType1Code | Annual | Annual statement report. |
OBExternalStatementType1Code | Interim | Adhoc or customised statement period. |
OBExternalStatementType1Code | RegularPeriodic | Regular pre-agreed reporting statement. |
These following ISO Enumerations are used in the Accounts APIs.
ISO Data Type | Fields | ISO Enumeration Values URL |
---|---|---|
Min3Max4Text | MerchantCategoryCode | https://www.iso.org/standard/33365.html |
ActiveOrHistoricCurrencyCode | Currency | https://www.iso20022.org/external_code_list.page |
CountryCode | Country | https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements |
ExternalBankTransactionFamily1Code | BankTransactionCode/Code | https://www.iso20022.org/external_code_list.page |
ExternalBankTransactionSubFamily1Code | BankTransactionCode/SubCode | https://www.iso20022.org/external_code_list.page |
The enumerated values specified by Open Banking are documented in Swagger specification and Namespaced Enumerations page.
The Swagger Specification for Account Information APIs can be downloaded from the following links: