Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
outlinetrue

Version Control

VersionDateAuthorComments
1.0.023 Jun 2017Open Banking Read/Write API Team

This is the Baseline version. No Changes from v1.0-rc4.

1.1.031 Aug 2017Open Banking Read/Write API Team

Includes 9 fixes, 5 clarifications and 14 enhancements. Please see the release note for details. Changes from v1.1-rc2: More explicit wording around Non-Repudiation not to be implemented for v1.x

Release Note

This release note explains what's new in The Account and Transaction API Specifications v1.1.0.

Fixes

  • In Accounts Transactions sequence diagram, removed Step 4 Request data response to the PSU.

  • Corrected the case for Links.First, Links.Last, Links.Next, Links.Prev, Links.Self and Meta.TotalPages (updated Basics/Pagination, Basics / Return & Error Codes / 400 (Bad Request) v/s 404 (Not Found), and Data Model / High Level Payload Structure / Response Structure).
  • Removed special characters in the Frequency field for Data Model / Data Payload - Resources / Standing Orders / Data Dictionary.
  • Corrected the Pattern for the ActiveOrHistoricCurrencyCode class from [A-Z]{3,3} to ^[A-Z]{3,3}$ to limit the field to 3 characters.
  • Corrected the Pattern for the CountryCode class to be specified as ^[A-Z]{2,2}$ instead of [A-Z]{2,2} to limit the field to 2 characters.
  • In Usage Examples, have corrected "AwaitingAuthentication" to "AwaitingAuthorisation"
  • Updated Usage Example for /products endpoint to align with Data Dictionary.
  • Updated Pagination Response JSON payload to correctly separate one of the JSON properties by inclusion of a comma.
  • Corrected a mis-spelling from "UFT-8" to "UTF-8".

Clarifications

  • Added details and updated examples on the various date formats used outside of the JSON payload (updated Examples, Basics / Date formats, and Basics / Non-repudiation / Process for signing a payload).
  • Clarified that Timezone offsets of -00:00 are not permitted in ISO-8601 (updated Examples, and all default dates in Data Model / Data payload - resources).
  • Clarified that all dates in HTTP headers are represented as RFC 7231 Full Dates. For example: Sun 3 Sep 2017 19:43:31 UTC
  • Clarified that a status of 403 should not be used to indicate a time-out of the access token, and that a 403 indicates that re-authentication of the PSU will not help.
  • Clarified that digital signatures must NOT be implemented for v1.x specification.

Enhancements

  • Metadata fields in the /transactions response now include an earliest available transaction date AND a latest available transaction date (updated Examples, Data Model / High Level Payload Structure / Response Structure / Meta, and default values specified in the Data Payload sections).
  • Added a new section to cater for reversals (Security & Access Control / Consent Authorization / Permissions / Reversing Entries).
  • Added a new section to specify the default character set as UTF-8 (Basics / Character Encoding). 
  • All datetime fields returned by the API must have the Timezone specified (updated Examples and added a new section Basics / Date Format).
  • Specified min and max page sizes for pagination (updated section on Basics / Pagination).
  • Sort Code and Account Number are now stored in the Account identification section together (in the Identification field), and a new SchemeName has been created for SortCodeAccountNumber (updated Examples, Data Model / Data Payload - Resources / Accounts / Data Dictionary, Data Model / Data Payload - Resources / Beneficiaries / Data Dictionary, Data Model / Data Payload - Resources / Standing Orders / Data Dictionary, and Data Model / Data Payload - Enumerations).

  • Extended the Standing Order Frequency pattern to include weekends and clarified pattern description (updated Data Model / Data Payload - Resources / Standing Orders / Data Dictionary).
  • Changed the BankTransactionCode to be the ISO 20022 code description, with all delimiters removed (updated Data Model / Data Payload - Resources / Transactions).
  • Add a Retry-After header for the HTTP 429 Too Many Requests response (updated Basics / Return & Error Codes, Basics / Headers / Response Headers, and Alternate Error Flows showing 429 as an optional implementation).
  • Added 405 and 406 as status codes (updated section on Basics / Response Headers).

  • Added clarifications to the Pagination section to state that the self link must be included in the response (Updated section Basic / Pagination).

  • Added a section describing resource URL path structures.

  • Added regex pattern for all Amount based fields under the Data Model / Data Payload. Removed pattern definition TotalDigits: 18 FractionDigits: 5.

  • Swagger Specification updated to include the Swagger Specification version number in the base of the URL (i.e. linked to this Specification).

Overview

This specification describes the Account Information and Transaction API flows and payloads.

The API endpoints described here allow an AISP to: 

  • Register an intent to retrieve account information by creating an "account request". This registers the data "permissions", expiration and transaction history timeframe the customer (PSU) has consented to provide to the AISP; and 
  • Subsequently retrieve account and transaction data

Document Overview

This document consists of the following parts:

Overview: Provides an overview of the scope of the API and the key decisions and principles that contributed to the specification.

Basics: The section identifies the resources, operations that are permitted on those resources, and various special cases.

Security & Access Control: Specifies the means for AISPs and PSUs to authenticate themselves and provide consent.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Data Model: Describes the data model for the API payloads.

Usage Examples: Examples for normal flows, and alternate flows.

Design Principles

RESTful APIs

The API adheres to RESTful API concepts where possible and sensible to do so.

However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.

References:

  • The highest level Data Description Language used is the JSON Schema : http://json-schema.org/
  • Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/
  • The Interface Description Language used is the Swagger Specification version 2.0 (also known as Open API) : http://swagger.io/ and 
    Github link macro
    linkhttps://github.com/OAI/OpenAPI-Specification

Standards

The OBIE principles for developing the new API standards:

  • OBIE will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.
  • The initial scope of these Standards is limited to current OBIE scope - i.e., meeting CMA remedies. However, the intention is that the scope of the Standards will extend to either include or align to initiatives to cover a wider scope (i.e., PSD2).
  • The Standards currently being reviewed include ISO20022, and FAPI.
  • OBIE will favour developer/user experience over and above adoption of existing Standards, in order to create a more future proof Standard.
  • OBIE will work with other relevant bodies to align with, contribute to and/or adopt other Standards work, especially relating to creation of Standards around APIs and JSON payloads

ISO 20022

The CMA Order requires the CMA9 Banks to be aligned with the Regulatory and Technical Standards (RTS) under PSD2.

A previous draft of the EBA RTS required that the interface "shall use ISO 20022 elements, components or approved message definitions". In keeping with that requirement, the API payloads are designed using the ISO 20022 message elements and components where available.

The principles we have applied to re-use of ISO message elements and components are:

  • Where relevant - the API payloads have been flattened so that they are more developer friendly. This has been a request from the developer community, and the stakeholders involved in the design workshop
  • Only elements that are required for the functioning of the API endpoint will be included in the API payload. API endpoints are defined for specific use-cases (not to be generically extensible for all use-cases). Hence - only elements that are required for the account and transaction information scope are included in the Account Information API payloads for v1.0 (as this is the agreed scope for our v1.0 specification).
  • We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.). An example is having latitude and longitude in decimal format - as this is how developers will work with latitude and longitude; or using simple types (e.g., a single date-time field) instead of a complex type (e.g., a choice field with a nesting of date and time).

Extensibility

Version 1.0 of the API only caters to read access to account and transaction information for BCAs and PCAs.

However - where possible the APIs have been designed to be extensible - so they can in the future cover additional account types (e.g., card accounts) and operations (e.g., write access).

Idempotency

The Account Information and Transaction APIs will not be idempotent for v1.0.

Non-Repudiation

Warning
titleImportant

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

Digital signatures will facilitate non-repudiation for Open Banking APIs. 

However, the solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / Non-repudiation.

Unique Identifiers (Id Fields)

A REST resource should have a unique identifier (e.g. a primary key) that can be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

However, considering that:

  • Some of the resources described in this specification do not have a primary key in the system of record.
  • For v1.0 it is not neccessary to individually address resources,

a decision has been made that Id fields will be specified for all resources - but be optional for all resources, except for the account resource.

The account resource needs to be addressed individually and must have a mandatory, unique and non-mutable identifier.

Scope

The APIs specified in this document provide the ability for AISPs to access a PSU's account and transaction information for domestic PCA and BCA accounts.

Out of Scope

This v1.0 specification does not cater for:

  • Write operations (the ability to create) standing orders, direct debits and beneficiaries.
  • Accounts other than PCAs and BCAs.
  • Progressive or changing consent - if the consent between the AISP and PSU changes, then the existing account-request object is deleted and a new account-request is created with the new consent/authorisation details.
  • The ability for the AISP to pre-specify the list of accounts that have been agreed with the PSU for consent/authorisation. At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time (e.g, customers adding or deleting accounts) affects the original agreed authorisation. 
  • The ability for the AISP to specify and "hints" for the types of accounts that have been agreed with the PSU for consent/authorisation (e.g., product or customer channel types). At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time affects the original agreed authorisation. 
  • Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are are not in the v1.0 specification.
  • Non-functional requirements and specification of caching and throttling.

Basics

Overview

The figure below provides a general outline of a account information requests and flow using the Account Info APIs.

Steps

Step 1: Request Account Information

  • This flow begins with a PSU consenting to allow an AISP to access account information data. 

Step 2: Setup Account Request

  • The AISP connects to the ASPSP that services the PSU's account(s) and creates an account-request resource. This informs the ASPSP that one of its PSUs is granting access to account and transaction information to an AISP. The ASPSP responds with an identifier for the resource (the AccountRequestId - which is the intent identifier).
  • This step is carried out by making a POST request to /account-requests endpoint
  • The setup payload will include these fields - which describe the data that the PSU has consented with the AISP:
    • Permissions - a list of data clusters that have been consented for access
    • Expiration Date - an optional expiration for when the AISP will no longer have access to the PSU's data
    • Transaction Validity Period - the From/To date range which specifies a transaction history period which can be accessed by the AISP
  • An AISP may be a broker for data to other 4th parties, and so it is valid for a customer to have multiple account-requests for the same accounts, with different consent/authorisation parameters agreed

Step 3: Authorise Consent

  • The AISP redirects the PSU to the ASPSP. The redirect includes the AccountRequestId generated in the previous step. This allows the ASPSP to correlate the account-request that was setup. The ASPSP authenticates the PSU. The ASPSP updates the state of the account-request resource internally to indicate that the account request has been authorised.
  • The principle we have agreed is that consent is managed between the PSU and the AISP - so the account-request details cannot be changed (with the ASPSP) in this step. The PSU will only be able to authorise or reject the account-request details in its entirety.
  • During authorisation - the PSU selects accounts that are authorised for the AISP request (in the ASPSP's banking interface)
  • The PSU is redirected back to the AISP.

Step 4: Request Data

  • This is carried out by making a GET request the relevant resource.
  • The unique AccountId(s) that are valid for the account-request will be returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token.

Sequence Diagram

Code Block
themeMidnight
titleAccount Info - High Level Flow
linenumberstrue
collapsetrue
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 request
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-requests
ASPSP Resource Server -> AISP: HTTP 201 (Created), AccountRequestId
AISP -> PSU: HTTP 302 (Found), Redirect (AccountRequestId)
 
note over PSU, ASPSP Resource Server
Step 3: Authorise consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (AccountRequestId)
PSU <-> ASPSP Authorisation Server: authenticate
PSU <-> ASPSP Authorisation Server: SCA if required
PSU <-> ASPSP Authorisation Server: select accounts
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
 
  
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

Actors

ActorAbbreviationTypeSpecializesDescription
Payment Service UserPSUPersonN/AA natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10))
Payment Service ProviderPSPLegal EntityN/AA legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11)
Account Servicing Payment Service ProviderASPSPLegal EntityPSP

An ASPSP is a PSP that provides and maintains a payment account for a payment services user (PSD 2 Article 4(15).

The CMA 9 are all ASPSPs.

Third Party Providers / Trusted Third PartiesTPPLegal EntityPSP

A party other than an ASPSP that provides payment related services.

The term is not actually defined in PSD2, but is generally deemed to include all payment service providers that are 3rd parties (the ASPSP and the PSU to whom the account belongs being the first two parties)

Payment Initiation Service ProviderPISPLegal EntityTPP

A TPP that provides Payment Initiation Services.

PSD2 does not offer a formal definition. Article 4(18) quite circularly defines a PISP as a PSP that provides Payment Initiation Services.

Account Information Service Provider

AISPLegal EntityTPP

A TPP that provides Account Information Services.

Again, PSD2 defines AISPs in Article 4(19) circularly as a PSP that provides account information services

Character Encoding

The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - Section 8.1).

However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "Happy Birthday 🎂🎂!" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP should respond with an HTTP 400 (Bad Request) status code.

Date Formats

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below:

Code Block
languagejs
themeMidnight
2017-04-05T10:43:07+00:00


All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

Code Block
languagejs
themeMidnight
Sun, 10 Sep 2017 19:43:31 UTC


JWT claims are expressed as a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. 

Resource URI Path Structure

The resources defined by these APIs can be addressed through a path structure consisting of the following parts:

  • An optional ASPSP specific path prefix
  • The constant string "open-banking"
  • The version of the APIs expressed as /v[major-version].[minor-version]/
  • The resource name

Examples:

/superbank/open-banking/v1.1/payments

/open-banking/v1.0/payments

/apis/open-banking/v1.1/payments

Headers

Request Headers

The following headers SHOULD be inserted by the TPP in each API call:

Header ValueNotesPOSTGETDELETE
x-fapi-financial-id

The unique id of the ASPSP to which the request is issued.

The unique id will be issued by OB.

MandatoryMandatoryMandatory
x-fapi-customer-last-logged-time

The time when the PSU last logged in with the TPP.

OptionalOptionalOptional
x-fapi-customer-ip-address

The PSU's IP address if the PSU is currently logged in with the TPP.

OptionalOptionalOptional
x-fapi-interaction-id

An RFC4122 UID used as a correlation id.

If provided, the ASPSP must "play back" this value in the x-fapi-interaction-id response header.

OptionalOptionalOptional
Authorization

Standard HTTP Header; Allows Credentials to be provided to the Authorisation / Resource Server depending on the type of resource being requested. For OAuth 2.0 / OIDC, this comprises of either the Basic / Bearer Authentication Schemes.

MandatoryMandatoryMandatory
Content-Type

Standard HTTP Header; Represents the format of the payload being provided in the request.

This must be set to application/json.

MandatoryDo not useDo not use
Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.

If set, it must have the value application/json.

If set to any other value, ASPSP must respond with a 406 Not Acceptable.

OptionalOptionalOptional
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

Mandatory for requests that contain a payload.

A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means of non-repudiation.

This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

Not for v1.xNot for v1.xNot for v1.x

(Reference: Section 6.3 - Financial API — Part 1: Read Only API Security Profile (Implementer’s Draft).)

Whether the PSU is present or not-present is identified via the x-fapi-customer-ip-address header. If the PSU IP address is supplied, it is inferred that the PSU is present during the interaction.

The implications to this are:

  • ASPSPs will need to rely on AISPs assertion.
  • As agreed at TDA (18/05) It will be up to the ASPSPs to interpret the 4-times customer not present rule - to be within the “spirit” of the RTS requirement.
  • This is dependent on GDPR considerations on the AISP passing a PSU's IP address to an ASPSP.

Response Headers

Header ValueNotesMandatory ?
Content-Type

Standard HTTP Header; Represents the format of the payload returned in the response.

The ASPSP must return Content-type: application/json as a content header in response to requests that return a HTTP body (all post and get requests)

Conditionally Mandatory
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

Mandatory for requests that contain a payload.

A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means of non-repudiation.

This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

Not for v1.x
x-fapi-interaction-id

An RFC4122 UID used as a correlation id.

This must be the same value provided in the x-fapi-interaction-id request header.

Mandatory if provided in the request.

Conditionally Mandatory
Retry-After


Header indicating the time (in seconds) that the TPP should wait before retrying an operation.

The ASPSP should include this header along with responses with the HTTP status code of 429 (Too many requests).

Optional

Return & Error Codes

The following are the HTTP response codes for the different HTTP methods - across all Account Info API endpoints.

Situation

HTTP Status

Notes

Returned by POSTReturned by GETReturned by DELETE
Query completed successfully200 OK
NoYesNo
Normal execution. The request has succeeded.201 CreatedThe operation results in the creation of a new resource.YesNoNo
Delete operation completed successfully204 No Content
NoNoYes

Account Request has malformed, missing or non-compliant JSON body or URL parameters

400 Bad RequestThe requested operation will not be carried out.YesNoNo

Authorization header missing or invalid token

401 Unauthorized

The operation was refused access.

Re-authenticating the PSU may result in an appropriate token that can be used.

YesYesYes

Token has incorrect scope or a security policy was violated.

403 Forbidden

The operation was refused access.

Re-authenticating the PSU is unlikely to remediate the situation.

YesYesYes
The TPP tried to access the resource with a method that is not supported.405 Method Not Allowed
YesYesYes
The request contained an accept header that requested a content-type other than application/json and a character set other than UTF-8406 Not Acceptable
YesYesYes
The operation was refused as too many requests have been made within a certain timeframe.429 Too Many Requests

Throttling is a NFR.

The ASPSP should include a Retry-After header in the response indicating how long the TPP must wait before retrying the operation.

YesYesYes
Something went wrong on the API gateway or micro-service500 Internal Server ErrorThe operation failed.YesYesYes

An ASPSP MAY return other standard HTTP status codes (e.g. from gateways and other edge devices) as described in RFC 7231 - Section 6.

400 (Bad Request) v/s 404 (Not Found)

When a TPP tries to request a resource URL with an resource Id that does not exist, the ASPSP must respond with a 400 (Bad Request) rather than a 404 (Not Found).

E.g., if a TPP tries to GET /accounts/22289 where 22289 is not a valid AccountId, the ASPSP must respond with a 400.

When a TPP tries to request a resource URL that results in no business data being returned (e.g. a request to retrieve standing order on an account that does not have standing orders) the ASPSP must respond with a 200 (OK) and set the array to be empty.

If the TPP tries to access a URL for a resource that is not defined by these specifications (e.g. GET /card-accounts), the ASPSP may choose to respond with a 404 (Not Found).

If an ASPSP has not implemented an optional API, it must respond with a 404 (Not Found) for requests to that URL.

The table below illustrates some examples of expected behaviour:

SituationRequestResponse
TPP attempts to retrieve an account with an AccountId that does not existGET /accounts/1001400 (Bad Request)
TPP attempts to retrieve a resource that is not definedGET /credit-cards404 (Not Found)

TPP attempts to retrieve a resource that is in the specification, but not implemented by the ASPSP.

E.g., an ASPSP has chosen not to implement the bulk direct-debit endpoint

GET /direct-debits404 (Not Found)
TPP attempts to retrieve standing orders for an AccountId that does not existsGET /accounts/1001/standing-orders400 (Bad Request)
TPP attempts to retrieve standing orders for an AccountId that exists, but does not have any standing ordersGET /accounts/1000/standing-orders
200 OK
{
  "Data": {
    "StandingOrder": []
  },
  "Links": {
    "Self": "/accounts/1000/standing-orders/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

403 (Forbidden)

When a TPP tries to access a resource that it does not have permission to access, the ASPSP must return a 403 (Forbidden).

The situation could arise when:

  • The TPP uses an access token that does not have the approporiate scope to access the requested resource.
  • The TPP does not have a consent authorisation for the AccountId
    E.g., an attempt to access GET /accounts/2001 or /accounts/2001/transactions when the PSU has not selected AccountId 2001 for authorisation.
  • The TPP does not have a consent authorisation with the right Persmissions to access the requested resource.
    E.g., an attempt to access GET /standing-orders when the ReadStandingOrdersBasic permission was not included in the consent authorisation.
  • The TPP attempted to access a resource with an Id that it does not have access to.
    E.g., an attempt to access GET /account-requests/1001 where an account-request resource with Id 1001 belongs to another TPP.

When the TPP uses an access token that is no longer valid, the situation could potentially be remedied by asking the PSU to re-authenticate. This should be indicated by a 401 (Unauthorized) status code.

429 (Too Many Requests)

When a TPP tries to access a resource too frequently the ASPSP may return a 429 (Too Many Requests).  This is a Non Functional Requirement and is down to individual ASPSPs to decide throttling limits. 

This situation could arise when:

  • The TPP has not implemented caching, it requests transactions for a PSU account, and constantly re-requests the same transactions 
  • Similarly for any of the PSU information endpoints 

Pre-Conditions

The following pre-conditions must be satisfied in order to use these APIs:

Pre-conditions for TPPs

  1. The TPP must have completed onboarding on the Open Banking Directory
  2. The TPP must have registered one or more software statements with the Open Banking Directory. The software statement must have "accounts" as one of the required scopes.
  3. The TPP must have valid network and signing certificates issued by Open Banking.
  4. The TPP must have completed registration with each of the ASPSPs that it wants to transact with and have been issued with a client-id.

Pre-conditions for ASPSPs

  1. The ASPSP must have completed onboarding on the Open Banking Directory
  2. The ASPSP must have valid network and signing certificates issued by Open Banking

Idempotency

The API for creating an account-request resource is not idempotentOnce the API has been called, the state of the underlying resource changes.

If a time-out error occurs - then we would expect an AISP to create a new account-request resource - rather than try with the same resource.

Non-repudiation

Warning
titleImportant

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

The solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / Non-repudiation.

Overview

The APIs require TLS 1.2 Mutual Authentication and this can be used as a means of non-repudiation. However, it would be difficult to maintain digital records and evidence of non-repudiation if the API only relied on TLS 1.2.

A solution for non-repudiation that does not rely on TLS, would be achieved by providing a JWS with detached content (as defined in RFC 7515 - Appendix F) in the HTTP header of each API request.

The HTTP body would form an un-encoded payload as defined in RFC 7797.

The JWS would be signed using an algorithm that supports asymmetric keys.

A request would be signed by a TPP's private key  and a response would be signed by the ASPSP's private key.

OB Directory will provide and host the necessary certificates containing the corresponding public keys so that hte signature can be verified.

Specification

The TPP must sign the HTTP body of each API request that has an HTTP body. (e.g. GET requests do not have an HTTP body and are not signed.)

The ASPSP must sign the HTTP body of each API response that it produces which has an HTTP body.

The ASPSP should verify the signature of API requests that it receives before carrying out the request. If the signature fails validation, the ASPSP must respond with a 400 (Bad Request).

The ASPSP must reject any API requests that should be signed but do not contain a signature in the HTTP header with a 400 (Bad Request) error.

The TPP should verify the signature of API responses that it receives.

Process for signing a payload

Step 1: Identify the private key and corresponding signing certificate to be used for signing

The signer must use a private key that has a corresponding digital certificate (that contains the corresponding public key) issued by OB.

The signing certificate must be valid at the time of creating the JWS.

Step 2: Form the JOSE Header

The JOSE header for the signature must contain the following fields

Claim

Description

alg

The algorithm that will be used for signing the JWS.

The list of valid algorithms is here https://tools.ietf.org/html/rfc7518#section-3.1.

The algorithms that will be supported by OB will be specified in the future.

kid

This must match the certificate id of the certificate selected in step 1.

b64

This must have the boolean value false.

This indicates that the message payload is not base64 url encoded.

(See RFC 7797 - The "b64" header Parameter)

http://openbanking.org.uk/iat

This must be a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. 

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names)

http://openbanking.org.uk/iss

This must be a string containing the id of the TPP. This must match the dn of the signing certificate.

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names)

crit

This must be a string array consisting of the values "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"

This indicates that the JWS signature validator must understand and process the three additional claims.

Step 3: Compute the JWS

The signer must compute the signature as a detached JWS as defined in RFC 7515.

Code Block
languagejs
themeMidnight
payload = base64Encode (JOSEHeader) + "." + base64Encode( json)
detachedJWS = base64Encode( JOSEHeader) + ".." + base64Encode ( encrypt (privateKey, base64Encode(json)))

Step 4: Add the JWS as a HTTP header 

The signer must include an HTTP header called x-jws-signature with its value set to the signature computed in Step 3.

Code Block
languagejs
themeMidnight
x-jws-signature: V2hhdCBoYXRoIGdvZCB3cm91Z2h0ID8=..QnkgR2VvcmdlLCBzaGUncyBnb3QgaXQhIEJ5IEdlb3JnZSBzaGUncyBnb3QgaXQhIE5vdyBvbmNlIGFnYWluLCB3aGVyZSBkb2VzIGl0IHJhaW4/

Process for verifying a signature

Step 1: Extract the components from the JWS 

The verifier must extract and decode the JOSE header and signature from the JWS provided in the x-jws-signature http header

Code Block
languagejs
themeMidnight
JWSParts[] = detachedJWS.tokenize("..");
JOSEHeader = base64Decode (JWSParts[0]);
Signature = JWSParts[1];
ExpectedSignedPayload = JWSParts[0] + "." + base64Encode( httpBody)

Step 2: Validate the JOSE header and certificate

The verifier must validate the JOSE header to ensure that it is a valid json object with only the claims specified in Process for Signing a Payload - Step 2.

The verifier must ensure that the specified alg is one of the algorithms specified by OB.

The verifier must ensure that the specified kid is valid and a signing certificate with the specified key id can be retrieved from the OB directory.

The verifier must ensure that the certificate is valid.

The verifier must ensure that the b64 claim is set to false.

The verifier must ensure that the http://openbanking.org.uk/iat claim has a date-time value set in the past.

The veriier must ensure that the http://openbanking.org.uk/iss claim matches the dn of the certificate.

The verifier must ensure that the crit claim does not contain additional critical elements.

Step 3: Verify the signature

The verifier must verify the signature by decrypting it and ensuring that it matches the ExpectedSignedPayload.

Code Block
languagejs
themeMidnight
DecryptedPayload = base64Decode ( decrypt ( publicKey, Signature));

Sample JOSE Header

Code Block
languagejs
themeMidnight
{
	"alg": "",
	"kid": "90210ABAD",
	"b64": false,
	"http://openbanking.org.uk/iat": 1501497671,
	"http://openbanking.org.uk/iss": "C=UK, ST=England, L=London, O=Acme Ltd.",
	"crit": [ "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"]
]

Filtering

Limited support for filtering is provided on the transactions resource.

Transactions can be filtered based on their Booking Date using the fromBookingDateTime and toBookingDateTime parameters

The dates MUST be specified in ISO8601 format. The date MUST NOT include a timezone.

The filter values will be assumed to refer to the same timezone as the timezone in which the booking date for the account is maintained.

The ASPSP must treat the following as valid input:

  • non-working days (e.g. a sunday or a bank holiday) or any other days on which no transactions are recorded
  • dates that fall outside the range for which transaction information is provided through APIs
  • dates that fall outside the range for which a consent authorisation is available.

In the above situations, the ASPSP must return data for the remaining valid period specified by the filter.

Code Block
languagejs
themeMidnight
titleExamples for filtering transactions
linenumberstrue
// All transactions from 1st Jan, 2015
GET /transactions?fromBookingDateTime=2015-01-01T00:00:00

// All transactions in 2016
GET /transactions?fromBookingDateTime=2016-01-01T00:00:00&toBookingDateTime=2016-12-31T23:59:59

// All transactions in a specific account upto 31-Mar-2017
GET /accounts/1/transactions?toBookingDateTime=2017-03-31T23:59:59

Pagination

An ASPSP MAY provide a paginated response for GET operations that return multiple records.

In such a situation, the ASPSP MUST:

  • If a subsequent page of resource records exists, the ASPSP must provide a link to the next page of resources in the Links.Next field of the response. The absence of a next link would indicate that the current page is the last page of results.
  • If a previous page of resource records exists, the ASPSP must provide a link to the previous page of resources in the Links.Prev field of the response. The absence of a prev link would indicate that the current page is the first page of results.

For a paginated responses, the ASPSP SHOULD ensure that the number of records on a page are within reasonable limits - a minimum of 25 records (except on the last page where there are no further records) and a maximum of 1000 records.

Additionally, the ASPSP MAY provide:

  • A link to the first page of results in the Links.First field.
  • A link to the last page of results in the Links.Last field.
  • The total number of pages in the Meta.TotalPages field.

As with all other responses, the ASPSP MUST include a "self" link to the resource in the Links.Self field as described in the Links sections.

This standard does not specify how the pagination parameters are passed by the ASPSP and each ASPSP may employ their own mechanisms to paginate the response.

If the original request from the AISP included filter parameters, the paginated response must return only results that match the filter.

ASPSPs are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.

Regulatory Considerations

Warning
titleNon-normative guidance

This section provides non-normative guidance on how the specifications can be used to comply with certain requirements of PSD2 and the RTS. This is not an exhaustive list. Detailed analysis will be provided separately - with full traceability matrix of requirements.

Although this specification refers to the use of SCA, the use of SCA is not mandated until the RTS comes into effect.

The RTS is not finalised at the point of publishing this version of the specification - this may lead to some changes as new drafts of the RTS are released.

RTS - Article 10

  1. Subject to paragraph 2 of this Article and to compliance with the requirements laid down in paragraphs 1, 2 and 3 of Article 2, payment service providers are exempted from the application of strong customer authentication where a payment service user is limited to accessing either or both of the following items online without disclosure of sensitive payment data:
    (a) the balance of one or more designated payment accounts; 
    (b) the payment transactions executed in the last 90 days through one or more designated payment accounts.
  2. For the purpose of paragraph 1, payment service providers are not exempted from the application of strong customer authentication where either of the following condition is met:
    (a) the payment service user is accessing online the information specified in points (a) and (b) of paragraph 1 for the first time; 
    (b) the last time the payment service user accessed online the information specified in point (b) of paragraph 1 and strong customer authentication was applied more than 90 days ago.

The ASPSP can determine if the conditions in paragraph 1 are met by examining the Account Request resource. In such a situation the Account Request will have:

  • The only requested permission is ReadBalances OR
  • All of the following are true:
    • The requested permissions are limited to the following: ReadBalance, ReadTransactionsBasic, ReadTransactionsCredits, ReadTransactionsDebits
    • The TransactionFromDateTime and ExpirationDateTime are both specified.
    • The ExpirationDateTime is the current date or a future date.
    • and the difference between TransactionFromDateTime and ExpirationDateTime is less than or equal to 90 days

The ASPSP must implement the necessary checks to ensure that the PSU is not accessing the data for the first time (as specified in Para 2(a)) - this is an implementation issue for the ASPSP.

If the ASPSP choses to re-authenticate the PSU every 90 days, the ASPSP should limit the validity of the refresh tokens that they issue to 90 days. 

RTS - Article 31(5)

Account information service providers shall be able to access information from designated payment accounts and associated payment transactions held by account servicing payment service providers for the purposes of performing the account information service in either of the following circumstances:
(a) whenever the payment service user is actively requesting such information;
(b) where the payment service user is not actively requesting such information, no more than four times in a 24 hour period, unless a higher frequency is agreed between the account information service provider and the account servicing payment service provider, with the payment service user’s consent.

Although it is difficult to determine what constitutes a PSU "actively requesting information", the ASPSP may utilise the FAPI headers (x-fapi-customer-last-logged-time and x-fapi-customer-ip-address) to make a determination of whether the PSU is "actively requesting such information".

Endpoints

This section looks at the list of available API endpoints to access Account Information and Transaction data. For detail on the request and response objects - refer to the Data Model section of the specification.

The ASPSP must implement the API end-points in the table below that are marked as mandatory.

The ASPSP may optionally implement the API end-points that are marked as non-mandatory.

If an ASPSP has not implemented an optional API, it must respond with a 404 (Not Found) for requests to that URL.

Endpoint design considerations:

  • Having resources that are finer grained (e.g., beneficiaries, direct-debits, standing-orders) means that we can, in the future, manage these resources (with unique identifiers)
  • While balances is not a typical resource - we believe having a /accounts/{AccountId}/balances endpoint is simpler to understand than a URI to expand the /accounts resource 
  • Some ASPSPs were uncomfortable implementing the bulk APIs (e.g., /accounts , /transactions , /beneficiaries etc.) for v1.0 - so the bulk APIs have been specified as optional (these are endpoints 12 to 17). However - the bulk endpoint for /accounts is mandatory to discover what accounts have been authorised for the account-request.

ResourceHTTP OperationEndpointMandatory ?ScopeIdempotentParametersRequest ObjectResponse Object
1account-requestsPOSTPOST /account-requestsMandatoryaccountsNoPaginationOBReadRequest1OBReadResponse1
2account-requestsGETGET /account-requests/{AccountRequestId}Optionalaccounts
Pagination
OBReadResponse1
3account-requestsDELETEDELETE /account-requests/{AccountRequestId}MandatoryaccountsYesPagination

4accountsGET

GET /accounts

Mandatory

accounts
Pagination
OBReadAccount1
5accountsGETGET /accounts/{AccountId}Mandatoryaccounts
Pagination
OBReadAccount1
6balancesGETGET /accounts/{AccountId}/balancesMandatoryaccounts
Pagination
OBReadBalance1
7beneficiariesGETGET /accounts/{AccountId}/beneficiariesMandatoryaccounts
Pagination
OBReadBeneficiary1
8direct-debitsGETGET /accounts/{AccountId}/direct-debitsMandatoryaccounts
Pagination
OBReadDirectDebit1
9productsGETGET /accounts/{AccountId}/productMandatoryaccounts
Pagination
OBReadProduct1
10standing-ordersGETGET /accounts/{AccountId}/standing-ordersMandatoryaccounts
Pagination
OBReadStandingOrder1
11transactionsGETGET /accounts/{AccountId}/transactionsMandatoryaccounts

Pagination

Filtering


OBReadTransaction1
12balancesGETGET /balancesOptionalaccounts
Pagination
OBReadBalance1
13beneficiariesGETGET /beneficiariesOptionalaccounts
Pagination
OBReadBeneficiary1
14direct-debitsGETGET /direct-debitsOptionalaccounts
Pagination
OBReadDirectDebit1
15productsGETGET /productsOptionalaccounts
Pagination
OBReadProduct1
16standing-ordersGETGET /standing-ordersOptionalaccounts
Pagination
OBReadStandingOrder1
17transactionsGETGET /transactionsOptionalaccounts

Pagination

Filtering


OBReadTransaction

We have specified what are "mandatory" endpoints for the functioning of the Account Info APIs.

However, if ASPSPs do not provide direct debit, standing order or beneficiary details via existing online channels - the endpoints will be not be mandatory.

POST /account-requests 

Code Block
languagetext
themeMidnight
firstline1
titlePOST Account Request
linenumberstrue
POST /account-requests

The API allows the AISP to ask an ASPSP to create a new account-request resource.

  • This API effectively allows the AISP to send a copy of the consent to the ASPSP to authorise access to account and transaction information.
  • For v1.0 - we have made a decision to remove functionality for an AISP to pre-select a set of accounts (i.e., the SelectedAccounts block). This is because the behaviour of the pre-selected accounts, after authorisation, is not clear form a Legal perspective at the time of writing the spec.
  • The ASPSP creates the account-request resource and responds with a unique AccountRequestId to refer to the resource.
  • Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

Account Request Status

The account-request resource that is created successfully must have one of the following Status code-list enumerations:


StatusStatus Description
1RejectedThe account request has been rejected.
2AwaitingAuthorisationThe account request is awaiting authorisation.

GET /account-requests/{AccountRequestId}

Code Block
languagetext
themeMidnight
firstline1
titleGET Account Request
linenumberstrue
GET /account-requests/{AccountRequestId}

An AISP can optionally retrieve a account-request resource that they have created to check its status. 

Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

Account Request Status

Once the PSU authorises the account-request resource - the Status of the account-request resource will be updated with "Authorised".

The available Status code-list enumerations for the account-request resource are:


StatusStatus Description
1RejectedThe account request has been rejected.
2AwaitingAuthorisationThe account request is awaiting authorisation.
3AuthorisedThe account request has been successfully authorised.
4RevokedThe account request has been revoked via the ASPSP interface.

DELETE /account-requests/{AccountRequestId}

Code Block
languagetext
themeMidnight
firstline1
titleDELETE Account Request
linenumberstrue
DELETE /account-requests/{AccountRequestId}

If the PSU revokes consent to data access with the AISP - the AISP should delete the account-request resource.

  • This is done by making a call to DELETE the account-request resource.
  • Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

GET Authorised Accounts

Code Block
languagetext
themeMidnight
firstline1
titleGET All Authorised Accounts
linenumberstrue
GET /accounts

The first step for an AISP after an account-request is authorised - is to call the GET /accounts endpoint. 

This will give the full list of accounts (the AccountId(s)) that the PSU has authorised the AISP to access. The AccountId(s) returned can then be used to retrieve other resources for an account. The selection of authorised accounts for v1.0 happens only at the ASPSP's interface.

The AISP will use an access token associated with the PSU issued through an authorization code grant.

GET Resources for a Specific Account

Code Block
languagetext
themeMidnight
firstline1
titleGET Resource for Specific Account
linenumberstrue
GET /accounts/{AccountId}
GET /accounts/{AccountId}/balances
GET /accounts/{AccountId}/beneficiaries
GET /accounts/{AccountId}/direct-debits
GET /accounts/{AccountId}/standing-orders
GET /accounts/{AccountId}/transactions
GET /accounts/{AccountId}/product

An AISP can retrieve the account information resources for the AccountId (which is retrieved in the call to GET /accounts).

The AISP will use an access token associated with the PSU issued through an authorization code grant.

GET Resources in Bulk

Code Block
languagetext
themeMidnight
firstline1
titleGET Resource for Bulk Accounts
linenumberstrue
GET /accounts
GET /balances
GET /beneficiaries
GET /direct-debits
GET /standing-orders
GET /transactions
GET /products

If an ASPSP has implemented the bulk retrieval endpoints - an AISP can optionally retrieve the account information resources in bulk. 

This will retrieve the resources for all authorised accounts linked to the account-request.

The AISP will use an access token associated with the PSU issued through an authorization code grant.

Security & Access Control

API Scopes

The access tokens required for accessing the Account Info APIs must have at least the following scope:

Code Block
languagetext
themeMidnight
firstline1
titleScopes
linenumberstrue
accounts 

Grants Types

AISPs must use a client credentials grant to obtain a token to access the account-requests resource.

AISPs must use a authorization code grant to obtain a token to access all other resources.

Consent Authorisation

OAuth 2.0 scopes are coarse grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine grained scopes (e.g. a scope to specify that account information should only be provided for certain time periods). 

consent authorisation is used to define the fine-grained scope that is granted by the PSU to the AISP.

The AISP must create an account-request 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 an AccountRequestId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

As part of the authorization code grant:

  • The ASPSP authenticates the PSU.
  • The ASPSP plays back the consent (registered by the AISP) back to the PSU - to get consent authorisation. The PSU may accept or reject the consent in its entirity (but not selectively).
  • The ASPSP presents the PSU a list of accounts to which the consent will apply.

Once these steps are complete, the consent is considered to have been authorised by the PSU.

Consent Elements

The Account Request resource consists of the following fields, that together form the elements of the consent provided by the PSU to the AISP:

  • Permissions: The set of data clusters that the PSU has consented to allow the AISP to access
  • ExpirationDateTime: The date-time up to which the consent is valid.
  • TransactionFromDateTime: The earliest booking date of transactions that the PSU has consented to provide access to the AISP.
  • TransactionToDateTime: The last booking date of transactions that the PSU has consented to provide access to the AISP.

Permissions

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)

The following combinations of permissions are disallowed and the ASPSP must not allow such account-requests to be created:

  • Account requests with an empty Permissions array
  • Account requests with a Permissions array that contains ReadTransactionBasic but does not contain at least one of ReadTransactionCredits and ReadTransactionDebits.
  • Account requests with a Permissions array that contains ReadTransactionDetail but does not contain at least one of ReadTransactionCredits and ReadTransactionDebits.
  • Account requests with a Permissions array that contains ReadTransactionCredits but does not contain at least one of ReadTransactionBasic and ReadTransactionDetails.
  • Account requests with a Permissions array that contains ReadTransactionDebits but does not contain at least one of ReadTransactionBasic and ReadTransactionDetails.
PermissionsEndpointsBusiness LogicData Cluster Description
ReadAccountsBasic

/accounts

/accounts/{AccountId}


Ability to read basic account information
ReadAccountsDetail

/accounts

/accounts/{AccountId}

Access to additional elements in the payload (the additional data elements are listed in the table below)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 payloadAbility 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 standing order information
ReadStandingOrdersDetail/standing-orders
/accounts/{AccountId}/standing-orders
Access to additional elements in the payloadAbility to read account identification details for beneficiary of the standing order
ReadTransactionsBasic/transactions
/accounts/{AccountId}/transactions

Permissions must also include at least one of:

  • ReadTransactionsCredits
  • ReadTransactionsDebits

Ability to read basic transaction information

ReadTransactionsDetail/transactions
/accounts/{AccountId}/transactions

Access to additional elements in the payload

Permissions must also include at least one of

  • ReadTransactionsCredits
  • ReadTransactionsDebits

Ability to read transaction data elements which may hold silent party details

ReadTransactionsCredits/transactions
/accounts/{AccountId}/transactions

Access to credit transactions.

Permissions must also include one of:

  • ReadTransactionsBasic
  • ReadTransactionsDetail
Ability to read only credit transactions
ReadTransactionsDebits/transactions
/accounts/{AccountId}/transactions

Access to debit transactions.

Permissions must also includeone of:

  • ReadTransactionsBasic
  • ReadTransactionsDetail
Ability to read only debit transactions
ReadProducts/products
/accounts/{AccountId}/product

Ability to read all product information relating to the account

The additional elements that are granted for "Detail" permissions are listed in this table.

All other fields (other than these fields listed) are available with the "Basic" Permission access. 

Permission - Detail CodesData Element NameOccurrenceXPath
ReadAccountsDetailAccount0..1OBReadAccount1/Data/Account/Account
ReadAccountsDetailServicer0..1OBReadAccount1/Data/Account/Servicer
ReadBeneficiariesDetailServicer0..1OBReadBeneficiary1/Data/Beneficiary/Servicer
ReadBeneficiariesDetailCreditorAccount0..1OBReadBeneficiary1/Data/Beneficiary/CreditorAccount
ReadStandingOrderDetailServicer0..1OBReadStandingOrder1/Data/StandingOrder/Servicer
ReadStandingOrderDetailCreditorAccount0..1OBReadStandingOrder1/Data/StandingOrder/CreditorAccount
ReadTransactionDetailTransactionInformation0..1OBReadTransaction1/Data/Transaction/TransactionInformation
ReadTransactionDetailBalance0..1OBReadTransaction1/Data/Transaction/Balance
ReadTransactionDetailMerchantDetails0..1OBReadTransaction1/Data/Transaction/MerchantDetails

Example behaviour of the Permissions for the ReadAccountsBasic and ReadAccountDetail codes is as follows:


Reversing Entries

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 ReadTransactionDebits, the ASPSP must include all debits including credit reversals.

Expiration Date Time

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 can be indefinite. The ExpirationDateTime is different to the RTS requirement for a PSU to re-authorise after 90 days - which is clarified in the "RTS and SCA Exemptions" section. The same account-request resource will be re-authenticated - with the same ExpirationDateTime as the original request.

The ExpirationDateTime applies to all Permissions (data clusters) being consented.

Transaction To/From Date Time

The TransactionToDateTime and the TransactionFromDateTime specify the period for consented transaction history. The AISP will be restricted to accessing transactions within this period when accessing the transactions resource.

Both the fields are optional and one can be specified without the other.

Account Request Status

The Account Request resource can have one of the following status codes after authorisation has taken place:


StatusDescription
1AuthorisedThe account request has been successfully authorised.
2RejectedThe account request has been rejected.
3RevokedThe account request has been revoked via the ASPSP interface.

Error Condition

If the PSU does not complete a successful consent authorisation (e.g. if the PSU is not authenticated successfully), the authorization code grant ends with a redirection to the TPP with an error response as described in RFC 6749 Section 4.1.2.1. The PSU is redirected to the TPP with a error parameter indicating the error that occoured.

Consent Revocation

A PSU can revoke consent for accessing account information at any point in time.

The PSU can 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. ASPSPs are under no obligation to notify AISPs regarding the revocation of authorisation in v1.0.

The PSU can request the AISP to revoke consent that it has authorised. If consent is revoked with the AISP:

  • The AISP must cease to access the APIs at that point (otherwise it may be in breach of GDPR).
  • The AISP should call the DELETE operation on the account-request resource to indicate to the ASPSP that the PSU has revoked consent.

Changes to Selected Account(s)

The PSU can 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 can 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 include (but are not limited to):

  • The account being closed.
  • The PSU's mandate to operate the account is revoked.
  • The account is barred or frozen.

In such a situation, only the affected account is removed from the list of selected accounts. The ASPSP must not revoke authorisation to other accounts.

Handling Expired Access Tokens

Access Token issued through Client Credentials Grant

When an access token issued through a Client Credentials Grant expires, the TPP must get a new access token by executing a client credential grant again.

Access Token issued through Authorization Code Grant

An ASPSP may issue a refresh token along with an access token at the end of an authorization code grant.

When an access token obtained through an authorization code grant expires, the TPP may attempt to get a new access and refresh token as defined in Section 6 of the OAuth 2.0 specification.

If the TPP fails to get an access token using a refresh token, the TPP would have to get the PSU to initiate a fresh authorisation code grant using an existing intent-id. 

An ASPSP may choose to simplify their implementation by ensuring that the access token and consent authorisation have the same period of validity - in such a situation, the access token will not expire within the lifetime of the consent authorisation and subsequently the ability to re-authenticate is not required.

Risk Scoring Information

Information for risk scoring and assessment will come via:

  • FAPI HTTP headers. These are defined in Section 6.3 of the FAPI specification and in the Headers section above.
  • Additional fields identified by the industry as business logic security concerns - which will be passed in the Risk section of the payload in the JSON object. 

No fields for business logic security concerns have been identified for the Account Info APIs for v1.0.

Swagger Specification

The Swagger Specification (v1.1.0) for Account Information APIs can be downloaded from the following links:

Data Model

High Level Payload Structure

This section gives an overview of the top level structure for the API payloads for the Account Info APIs.

Request Structure

The top level request structure for Account Info APIs:

Code Block
languagetext
themeMidnight
firstline1
titleAccount API Request
linenumberstrue
{
  "Data": {
    ...
  },
  "Risk": {
    ...
  }
}

The top level structure for the Account Info API POST requests will be:

  • Data

  • Risk

The Data section contains the request details.

A Risk section for the request structure has been separated out - so that this can evolve in isolation from request section of the payload.

Response Structure

The top level response structure for Account Info APIs:

Code Block
languagetext
themeMidnight
firstline1
titleAccount API Response
linenumberstrue
{
  "Data": {
    ...
  },
  "Risk": {
    ...
  },
  "Links": {
    ...
  ],
  "Meta": {
    ...
  }
}

In line with the principle on RESTful API practices - we are replaying the resource as part of the response.

Two additional top level sections are included for:

  • Links

  • Meta

The Links section is mandatory and will always contain URIs to related resources, 

The "Self" member is mandatory, the other members  "First", "Prev", "Next", "Last"  are optional.

For example:

Code Block
languagejs
themeMidnight
titleExample Links
linenumberstrue
  "Links": {
    "Self": "http://example.com/articles?page[number]=3&page[size]=1",
    "First": "http://example.com/articles?page[number]=1&page[size]=1",
    "Prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "Next": "http://example.com/articles?page[number]=4&page[size]=1",
    "Last": "http://example.com/articles?page[number]=13&page[size]=1"
  }


Meta

The Meta section is mandatory, but can be empty.

An optional member is "TotalPages" which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.

For example:

Code Block
languagejs
themeMidnight
titleExample Meta
linenumberstrue
  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
Identifying Available Transaction Period

The transactions for a particular range of dates may be excluded from the response because:

  • The ASPSP does not provide historical transactions during that date range.
  • The PSU has not consented to transactions for that date range.

The absence of transactions in the payload does not indicate that there were no transactions 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.

Data Payload - Consent Object

This data dictionary section gives the detail on the payload content for Account Information flow to request access to account information.

Account Requests - Request

The OBReadRequest1 object will be used for the call to:

  • POST /account-requests

UML Diagram

Notes:

  • The fields in the OBReadRequest1 object are described in the Consent Elements section above
  • No fields have been identified for the Risk section for v1.0 

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadRequest1
OBReadRequest1
OBReadRequest1
Data1..1OBReadRequest1/Data
OBReadData1
Permissions1..nOBReadRequest1/Data/PermissionsSpecifies the Open Banking account request types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.OBExternalPermissions1CodeReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadProducts
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
ExpirationDateTime0..1OBReadRequest1/Data/ExpirationDateTimeSpecified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.
ISODateTime
TransactionFromDateTime0..1OBReadRequest1/Data/TransactionFromDateTimeSpecified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.
ISODateTime
TransactionToDateTime0..1OBReadRequest1/Data/TransactionToDateTimeSpecified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.
ISODateTime
Risk1..1OBReadRequest1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info.OBRisk2

Account Requests - Response

The OBReadResponse1 object will be used for the:

  • Response to POST /account-requests
  • Call to GET /account-requests/{AccountRequestId}

UML Diagram

Notes:

  • The OBReadResponse1 object contains the same information as the OBReadRequest1 - but with additional fields:
    • AccountRequestId - to uniquely identify the account-request resource
    • Status
    • CreationDateTime
  • No fields have been identified for the Risk section for v1.0

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadResponse1
OBReadResponse1
OBReadResponse1
Data1..1OBReadResponse1/Data
OBReadDataResponse1
AccountRequestId1..1OBReadResponse1/Data/AccountRequestIdUnique identification as assigned to identify the account request resource.Max128Text
Status0..1OBReadResponse1/Data/StatusSpecifies the status of the account request resource.OBExternalRequestStatus1Code

Authorised
AwaitingAuthorisation
Rejected

Revoked

CreationDateTime1..1OBReadResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime
Permissions1..nOBReadResponse1/Data/PermissionsSpecifies the Open Banking account request types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.OBExternalPermissions1CodeReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadProducts
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
ExpirationDateTime0..1OBReadResponse1/Data/ExpirationDateTimeSpecified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.
ISODateTime
TransactionFromDateTime0..1OBReadResponse1/Data/TransactionFromDateTimeSpecified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.
ISODateTime
TransactionToDateTime0..1OBReadResponse1/Data/TransactionToDateTimeSpecified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.
ISODateTime
Risk1..1OBReadResponse1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info.OBRisk2

Data Payload - Resources

This data dictionary section gives the detail on the payload content for the account information resource endpoints.

How the resources relate from a logical perspective is documented in the Logical Data Model: Account Info - Logical Model.

UML diagram notes:

  • All amount fields across the API endpoints use the ISO 20022 ActiveOrHistoricCurrencyAndAmount class. This is an XML attribute (with an embedded Currency field). Due to the limitations of the XML tool - the Currency field does not show in the UML diagram - however, is reflected in the Data Dictionary.

Accounts

The OBReadAccount1 object will be used for the call to:

  • GET /accounts/{AccountId}
  • GET /accounts

Resource Definition

The resource that represents the account to which credit and debit entries are made.

Each account resource will have a unique and immutable AccountId.

UML Diagram

Notes:

  • The Account and Servicer blocks replicate what is used consistently throughout the Account Information APIs.
  • This structure has been designed to:
    • Reflect the DebtorAccount and DebtorAgent (and similarly for CreditorAccount and CreditorAgent) structures in the PISP use case
    • Having a SchemeName for the Account and Servicer blocks means we can be flexible to accommodate multiple types of accounts (SortCodeAccountNumber or IBAN)
  • Where "SortCodeAccountNumber" is specified as the SchemeName in the Account identification section, the Identification field must be populated with the 6 digit Sort Code and 8 digit Account Number (a 14 digit field); and the Servicer section must not be populated
  • Where the "IBAN" is specified as the SchemeName in the Account identification section, the Identification field must be populated with the full IBAN; and the Servicer section should be populated with the "BICFI" as the SchemeName
  • The SecondaryIdentification element can be used for the roll number for building societies

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadAccount1
OBReadAccount1
OBReadAccount1

Data1..1OBReadAccount1/Data
OBReadDataAccount1

Account0..nOBReadAccount1/Data/AccountUnambiguous identification of the account to which credit and debit entries are made.OBAccount1

AccountId1..1OBReadAccount1/Data/Account/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

Currency1..1OBReadAccount1/Data/Account/CurrencyIdentification of the currency in which the account is held.

Usage: Currency should only be used in case one and the same account number covers several currencies
and the initiating party needs to identify which currency needs to be used for settlement on the account.
ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
Nickname0..1OBReadAccount1/Data/Account/NicknameThe nickname of the account, assigned by the account owner in order to provide an additional means of identification of the account.Max70Text

Account0..1OBReadAccount1/Data/Account/AccountProvides the details to identify an account.OBCashAccount1

SchemeName1..1OBReadAccount1/Data/Account/Account/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeIBAN SortCodeAccountNumber
Identification1..1OBReadAccount1/Data/Account/Account/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name0..1OBReadAccount1/Data/Account/Account/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text

SecondaryIdentification0..1OBReadAccount1/Data/Account/Account/SecondaryIdentificationThis is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

Servicer0..1OBReadAccount1/Data/Account/ServicerParty that manages the account on behalf of the account owner, that is manages the registration and booking of entries on the account, calculates balances on the account and provides information about the account.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBReadAccount1/Data/Account/Servicer/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBReadAccount1/Data/Account/Servicer/IdentificationUnique and unambiguous identification of the servicing institution.Max35Text

Balances

The OBReadBalance1 object will be used for the call to: 

  • GET /accounts/{AccountId}/balances
  • GET /balances

Resource Definition

Representation of the net increases and decreases in an account (AccountId) at a specific point in time.

An account (AccountId) can have multiple balance types (these follow the standard ISO 20022 balance type enumerations). If an ASPSP includes a credit line in an available balance - then the balance representation will have a section for the credit line amount and type.

UML Diagram

Notes:

  • Multiple balances can be returned (each with a different value for Type) for an account. This is for ASPSPs that show multiple balances in their online channels.
  • The CreditLine section can be repeated - as multiple credit lines may be included in an available balance.
  • A DateTime element has been used instead of a complex choice element of Date and DateTime. Where time elements do not exist in ASPSP systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadBalance1
OBReadBalance1
OBReadBalance1

Data1..1OBReadBalance1/Data
OBReadDataBalance1

Balance1..nOBReadBalance1/Data/BalanceSet of elements used to define the balance details.OBCashBalance1

AccountId1..1OBReadBalance1/Data/Balance/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

Amount1..1OBReadBalance1/Data/Balance/AmountAmount of money of the cash balance.ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1OBReadBalance1/Data/Balance/Amount/CurrencyA 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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
CreditDebitIndicator1..1OBReadBalance1/Data/Balance/CreditDebitIndicatorIndicates whether the balance is a credit or a debit balance.
Usage: A zero balance is considered to be a credit balance.
OBCreditDebitCodeCredit
Debit

Type1..1OBReadBalance1/Data/Balance/TypeBalance type, in a coded form.OBBalanceType1CodeClosingAvailable
ClosingBooked
Expected
ForwardAvailable
Information
InterimAvailable
InterimBooked
OpeningAvailable
OpeningBooked
PreviouslyClosedBooked

DateTime1..1OBReadBalance1/Data/Balance/DateTimeIndicates the date (and time) of the balance.ISODateTime

CreditLine0..nOBReadBalance1/Data/Balance/CreditLineSet of elements used to provide details on the credit line.OBCreditLine1

Included1..1OBReadBalance1/Data/Balance/CreditLine/IncludedIndicates whether or not the credit line is included in the balance of the account.

Usage: If not present, credit line is not included in the balance amount of the account.
xs:boolean

Amount0..1OBReadBalance1/Data/Balance/CreditLine/AmountAmount of money of the credit line.ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1OBReadBalance1/Data/Balance/CreditLine/Amount/CurrencyA 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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
Type0..1OBReadBalance1/Data/Balance/CreditLine/TypeLimit type, in a coded form.OBExternalLimitType1CodePre-Agreed
Emergency
Temporary

Beneficiaries

The OBReadBeneficiary1 object will be used for the call to: 

  • GET /accounts/{AccountId}/beneficiaries
  • GET /beneficiaries

Resource Definition

A resource that contains a set of elements that describe the list of trusted beneficiaries linked to a specific account (AccountId).

An account (AccountId) can have no trusted beneficiaries set up, or may have multiple beneficiaries set up.

In the case an ASPSP manages beneficiaries at a customer level (logged in user), instead of account level:

  • If a PSU selects multiple accounts for authorisation - then their beneficiaries apply consistently to all selected accounts (i.e., in the bulk endpoint /beneficiaries)
  • If a different PSU selects the same accounts - a different set of beneficiaries could be returned

This is the expected behaviour of the beneficiaries endpoints - in the case an ASPSP manages beneficiaries at a customer level:

  • The bulk endpoint /beneficiaries will return the unique list of beneficiaries against the PSU. In this case - the AccountId in the OBReadBeneficiary1 payload would be set to NULL / empty (even if the PSU only has one account).
  • The selected account endpoint /accounts/{AccountId}/beneficiaries will return the beneficiaries that could be accessible to the AccountId - based on the PSU. In this case - the AccountId will be populated in the payload

UML Diagram

Notes:

  • The Account and Servicer blocks replicate what is used consistently throughout the Account Information APIs to identify an account.
  • For the /accounts/{AccountId}/beneficiaries endpoint - the Account and Servicer blocks represent the account of the beneficiary that is receiving funds (so has been named the CreditorAccount - for consistency with the PISP use case).

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadBeneficiary1
OBReadBeneficiary1
OBReadBeneficiary1
Data1..1OBReadBeneficiary1/Data
OBReadDataBeneficiary1
Beneficiary0..nOBReadBeneficiary1/Data/Beneficiary
OBBeneficiary1
AccountId0..1OBReadBeneficiary1/Data/Beneficiary/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text
BeneficiaryId0..1OBReadBeneficiary1/Data/Beneficiary/BeneficiaryIdA unique and immutable identifier used to identify the beneficiary resource. This identifier has no meaning to the account owner.Max40Text
Reference0..1OBReadBeneficiary1/Data/Beneficiary/ReferenceUnique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money.

If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.
Max35Text
Servicer0..1OBReadBeneficiary1/Data/Beneficiary/ServicerParty that manages the account on behalf of the account owner, that is manages the registration and booking of entries on the account, calculates balances on the account and provides information about the account.
This is the servicer of the beneficiary account.
OBBranchAndFinancialInstitutionIdentification2
SchemeName1..1OBReadBeneficiary1/Data/Beneficiary/Servicer/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBReadBeneficiary1/Data/Beneficiary/Servicer/IdentificationUnique and unambiguous identification of the servicing institution.Max35Text
CreditorAccount0..1OBReadBeneficiary1/Data/Beneficiary/CreditorAccountProvides the details to identify the beneficiary account.OBCashAccount1
SchemeName1..1OBReadBeneficiary1/Data/Beneficiary/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeIBAN SortCodeAccountNumber
Identification1..1OBReadBeneficiary1/Data/Beneficiary/CreditorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text
Name0..1OBReadBeneficiary1/Data/Beneficiary/CreditorAccount/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text
SecondaryIdentification0..1OBReadBeneficiary1/Data/Beneficiary/CreditorAccount/SecondaryIdentificationThis is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

Direct Debits

The OBReadDirectDebit1 object will be used for the call to: 

  • GET /accounts/{AccountId}/direct-debits
  • GET /direct-debits

Resource Definition

A resource that contains a set of elements that describe the list of direct-debits that have been set up on a specific account (AccountId).

An account (AccountId) can have no direct debits set up, or may have multiple direct debits set up.

UML Diagram

Notes:

  • A DateTime element has been used - so that there is consistency across all API endpoints using dates. Where time elements do not exist in ASPSP systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadDirectDebit1
OBReadDirectDebit1
OBReadDirectDebit1

Data1..1OBReadDirectDebit1/Data
OBReadDataDirectDebit1

DirectDebit0..nOBReadDirectDebit1/Data/DirectDebitAccount to or from which a cash entry is made.OBDirectDebit1

AccountId1..1OBReadDirectDebit1/Data/DirectDebit/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

DirectDebitId0..1OBReadDirectDebit1/Data/DirectDebit/DirectDebitIdA unique and immutable identifier used to identify the direct debit resource. This identifier has no meaning to the account owner.Max40Text

MandateIdentification1..1OBReadDirectDebit1/Data/DirectDebit/MandateIdentificationDirect Debit reference. For AUDDIS service users provide Core Reference. For non AUDDIS service users provide Core reference if possible or last used reference.Max35Text

DirectDebitStatusCode0..1OBReadDirectDebit1/Data/DirectDebit/DirectDebitStatusCodeSpecifies the status of the direct debit in code form.OBExternalDirectDebitStatus1CodeActive
Inactive

Name1..1OBReadDirectDebit1/Data/DirectDebit/NameName of Service User.Max70Text

PreviousPaymentDateTime0..1OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentDateTimeDate of most recent direct debit collection.ISODateTime

PreviousPaymentAmount0..1OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmountThe amount of the most recent direct debit collection.ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1

OBReadDirectDebit1/Data/DirectDebit/

PreviousPaymentAmount/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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$

Product

The OBReadProduct1 object will be used for the call to: 

  • GET /accounts/{AccountId}/product
  • GET /products

Resource Definition

A resource that contains a set of elements that describe the product details specific to the account (AccountId).

An account (AccountId) can only have a single product.

UML Diagram

Notes:

  • An AccountId will only have one product - so the singe account endpoint will return only one product (for /accounts/{AccountId}/product)
  • However - for the bulk products endpoint (/products) - multiple products can be returned for multiple accounts

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadProduct1
OBReadProduct1
OBReadProduct1

Data1..1OBReadProduct1/Data
OBReadDataProduct1

Product0..nOBReadProduct1/Data/Product
OBProduct1

AccountId1..1OBReadProduct1/Data/Product/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

ProductIdentifier1..1OBReadProduct1/Data/Product/ProductIdentifierIdentifier within the parent organisation for the product. Must be unique in the organisation.xs:string

ProductType1..1OBReadProduct1/Data/Product/ProductTypeDescriptive code for the product category.OBExternalProductType1CodeBCA
PCA

ProductName0..1OBReadProduct1/Data/Product/ProductNameThe name of the product used for marketing purposes from a customer perspective. I.e. what the customer would recognise.xs:string

SecondaryProductIdentifier0..1OBReadProduct1/Data/Product/SecondaryProductIdentifierIdentifier within the parent organisation for the product. Must be unique in the organisation.xs:string

Standing Orders

The OBReadStandingOrder1 object will be used for the call to: 

  • GET /accounts/{AccountId}/standing-orders
  • GET /standing-orders

Resource Definition

A resource that contains a set of elements that describe the list of standing-orders that have been set up on a specific account (AccountId).

An account (AccountId) can have no standing orders set up, or may have multiple standing orders set up.

UML Diagram

Notes:

  • The Account and Servicer blocks replicate what is used consistently throughout the Account Information APIs to identify an account. 
  • For the /accounts/{AccountId}/standing-orders endpoint - the Account and Servicer blocks represent the account that is receiving funds (so has been named the CreditorAccount - for consistency with the PISP use case).
  • A DateTime element has been used - so that there is consistency across all API endpoints using dates. Where time elements do not exist in ASPSP systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00
  • The Amount elements all have embedded Currency elements - for consistency is ISO 20022, and across the other API endpoints

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadStandingOrder1
OBReadStandingOrder1
OBReadStandingOrder1

Data1..1OBReadStandingOrder1/Data
OBReadDataStandingOrder1

StandingOrder0..nOBReadStandingOrder1/Data/StandingOrderAccount to or from which a cash entry is made.OBStandingOrder1

AccountId1..1OBReadStandingOrder1/Data/StandingOrder/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

StandingOrderId0..1OBReadStandingOrder1/Data/StandingOrder/StandingOrderIdA unique and immutable identifier used to identify the standing order resource. This identifier has no meaning to the account owner.Max40Text

Frequency1..1OBReadStandingOrder1/Data/StandingOrder/Frequency

Individual Definitions:

EvryDay - Every day

EvryWorkgDay - Every working day

IntrvlWkDay - An interval specified in weeks (01 to 09), and the day within the week (01 to 07)

WkInMnthDay - A monthly interval, specifying the week of the month (01 to 05) and day within the week (01 to 07)

IntrvlMnthDay - An interval specified in months (between 01 to 06, 12, 24), specifying the day within the month (-5 to -1, 1 to 31)

QtrDay - Quarterly (either ENGLISH, SCOTTISH, or RECEIVED)

Individual Patterns:

EvryDay (ScheduleCode)

EvryWorkgDay (ScheduleCode)

IntrvlWkDay:IntervalInWeeks:DayInWeek (ScheduleCode + IntervalInWeeks + DayInWeek)

WkInMnthDay:WeekInMonth:DayInWeek (ScheduleCode + WeekInMonth + DayInWeek)

IntrvlMnthDay:IntervalInMonths:DayInMonth (ScheduleCode + IntervalInMonths + DayInMonth)

QtrDay: + either (ENGLISH, SCOTTISH or RECEIVED) ScheduleCode + QuarterDay

The regular expression for this element combines five smaller versions for each permitted pattern. To aid legibility - the components are presented individually here:

EvryDay

EvryWorkgDay

IntrvlWkDay:0[1-9]:0[1-7]

WkInMnthDay:0[1-5]:0[1-7]

IntrvlMnthDay:(0[1-6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01])

QtrDay:(ENGLISH|SCOTTISH|RECEIVED)

Full Regular Expression:

^(EvryDay)$|^(EvryWorkgDay)$|^(IntrvlWkDay:0[1-9]:0[1-7])$|^(WkInMnthDay:0[1-5]:0[1-7])$|^(IntrvlMnthDay:(0[1-6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01]))$|^(QtrDay:(ENGLISH|SCOTTISH|RECEIVED))$

Max35Text
^(EvryDay)$|^(EvryWorkgDay)$|^(IntrvlWkDay:0[1-9]:0[1-7])$|^(WkInMnthDay:0[1-5]:0[1-7])$|^(IntrvlMnthDay:(0[1-6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01]))$|^(QtrDay:(ENGLISH|SCOTTISH|RECEIVED))$
Reference0..1OBReadStandingOrder1/Data/StandingOrder/ReferenceUnique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money.

If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.
Max35Text

FirstPaymentDateTime0..1

OBReadStandingOrder1/Data/StandingOrder/

FirstPaymentDateTime

The date on which the first payment for a Standing Order schedule will be made.ISODateTime

FirstPaymentAmount0..1

OBReadStandingOrder1/Data/StandingOrder/

FirstPaymentAmount

The amount of the first Standing OrderActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1

OBReadStandingOrder1/Data/StandingOrder/

FirstPaymentAmount/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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
NextPaymentDateTime1..1

OBReadStandingOrder1/Data/StandingOrder/

NextPaymentDateTime

The date on which the next payment for a Standing Order schedule will be made.ISODateTime

NextPaymentAmount1..1

OBReadStandingOrder1/Data/StandingOrder/

NextPaymentAmount

The amount of the next Standing OrderActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1

OBReadStandingOrder1/Data/StandingOrder/

NextPaymentAmount/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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
FinalPaymentDateTime0..1

OBReadStandingOrder1/Data/StandingOrder/

FinalPaymentDateTime

The date on which the final payment for a Standing Order schedule will be made.ISODateTime

FinalPaymentAmount0..1

OBReadStandingOrder1/Data/StandingOrder/

FinalPaymentAmount

The amount of the final Standing OrderActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1

OBReadStandingOrder1/Data/StandingOrder/

FinalPaymentAmount/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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
Servicer0..1OBReadStandingOrder1/Data/StandingOrder/ServicerParty that manages the account on behalf of the account owner, that is manages the registration and booking of entries on the account, calculates balances on the account and provides information about the account.
This is the servicer of the beneficiary account.
OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1

OBReadStandingOrder1/Data/StandingOrder/

Servicer/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

OBExternalFinancialInstitutionIdentification2Code

BICFI
Identification1..1

OBReadStandingOrder1/Data/StandingOrder/

Servicer/Identification

Unique and unambiguous identification of the servicing institution.Max35Text

CreditorAccount0..1

OBReadStandingOrder1/Data/StandingOrder/

CreditorAccount

Provides the details to identify the beneficiary account.OBCashAccount1

SchemeName1..1

OBReadStandingOrder1/Data/StandingOrder/

CreditorAccount/SchemeName

Name of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeIBAN SortCodeAccountNumber
Identification1..1

OBReadStandingOrder1/Data/StandingOrder

/CreditorAccount/Identification

Beneficiary account identification.Max34Text

Name0..1

OBReadStandingOrder1/Data/StandingOrder/

CreditorAccount/Name

Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text

SecondaryIdentification0..1

OBReadStandingOrder1/Data/StandingOrder/

CreditorAccount/SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

Transactions

The OBReadTransaction1 object will be used for the call to:

  • GET /accounts/{AccountId}/transactions
  • GET /transactions

Resource Definition

A resource that describes a posting to an account that results in an increase or decrease to a balance.

For a specific date range - an account (AccountId) can have no transactions booked, or can have multiple transactions booked.

UML Diagram

Notes:

  • The use of the term "Transaction" has been made consistently in the Transaction endpoint payload (instead of "Entry" which is the ISO20022 element name)

  • A DateTime element has been used instead of a complex choice element of Date and DateTime. Where time elements do not exist in ASPSP systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00
  • The BookingDateTime has been set to mandatory - as all ASPSPs can provide this field for pagination and filtering. The BookingDateTime is the date the transaction is booked (or posted) and becomes immutable - which is not the date the transaction took place.

  • Either the BankTransactionCode (which is the ISO transaction code list), or ProprietaryBankTransactionCode, or both can be populated. While the expectation is that at least one of BankTransactionCode or ProprietaryBankTransactionCode are populated - we have decided not to enforce this behaviour in the payload structure - as this would require nesting elements, and introducing complex choice elements.

  • The BankTransactionCode (ISO) code-list is documented on the ISO20022 website: https://www.iso20022.org/external_code_list.page; and External Code Sets spreadsheet.

    • The ISO 20022 BankTransactionCode Code and SubCode are specified as a 4 letter codes. However - the principle we have applied for the code lists is to have longer more descriptive codes.
    • The BankTransactionCode Code and SubCode will be populated with the long form description of the ISO 20022 code, with delimiters removed. E.g., the Family Code "CNTR" has a description of "Counter Transactions" which is populated as "CounterTransactions"
  • ASPSPs must have the ability to provide transactions through APIs for a period that at least equals the period provided through their online channels.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadTransaction1
OBReadTransaction1
OBReadTransaction1

Data1..1OBReadTransaction1/Data
OBReadDataTransaction1

Transaction0..nOBReadTransaction1/Data/TransactionProvides further details on an entry in the report.OBTransaction1

AccountId1..1OBReadTransaction1/Data/Transaction/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

TransactionId0..1OBReadTransaction1/Data/Transaction/TransactionIdUnique identifier for the transaction within an servicing institution. This identifier is both unique and immutable.Max40Text

TransactionReference0..1OBReadTransaction1/Data/Transaction/TransactionReferenceUnique reference for the transaction. This reference is optionally populated, and may as an example be the FPID in the Faster Payments context.Max35Text

Amount1..1OBReadTransaction1/Data/Transaction/AmountAmount of money in the cash transaction entry.ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1OBReadTransaction1/Data/Transaction/Amount/CurrencyA 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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
CreditDebitIndicator1..1OBReadTransaction1/Data/Transaction/CreditDebitIndicatorIndicates whether the transaction is a credit or a debit entry.OBCreditDebitCodeCredit
Debit

Status1..1OBReadTransaction1/Data/Transaction/StatusStatus of a transaction entry on the books of the account servicer.OBEntryStatus1CodeBooked
Pending

BookingDateTime1..1OBReadTransaction1/Data/Transaction/BookingDateTimeDate and time when a transaction entry is posted to an account on the account servicer's books.

Usage: Booking date is the expected booking date, unless the status is booked, in which case it is the actual booking date.
ISODateTime

ValueDateTime0..1OBReadTransaction1/Data/Transaction/ValueDateTimeDate and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry.
Usage: If transaction entry status is pending and value date is present, then the value date refers to an expected/requested value date.
For transaction entries subject to availability/float and for which availability information is provided, the value date must not be used. In this case the availability component identifies the number of availability days.
ISODateTime

TransactionInformation0..1OBReadTransaction1/Data/Transaction/TransactionInformationFurther details of the transaction.
This is the transaction narrative, which is unstructured text.
Max500Text

AddressLine0..1OBReadTransaction1/Data/Transaction/AddressLineInformation that locates and identifies a specific address for a transaction entry, that is presented in free format text.Max70Text

BankTransactionCode0..1

OBReadTransaction1/Data/Transaction/

BankTransactionCode

Set of elements used to fully identify the type of underlying transaction resulting in an entry.OBBankTransactionCodeStructure1

Code1..1

OBReadTransaction1/Data/Transaction/

BankTransactionCode/Code

Specifies the family within a domain.ExternalBankTransactionFamily1Code

SubCode1..1

OBReadTransaction1/Data/Transaction/

BankTransactionCode/SubCode

Specifies the sub-product family within a specific family.ExternalBankTransactionSubFamily1Code

ProprietaryBankTransactionCode0..1

OBReadTransaction1/Data/Transaction/

ProprietaryBankTransactionCode

Set of elements to fully identify a proprietary bank transaction code.ProprietaryBankTransactionCodeStructure1

Code1..1

OBReadTransaction1/Data/Transaction/

ProprietaryBankTransactionCode/Code

Proprietary bank transaction code to identify the underlying transaction.Max35Text

Issuer0..1

OBReadTransaction1/Data/Transaction/

ProprietaryBankTransactionCode/Issuer

Identification of the issuer of the proprietary bank transaction code.Max35Text

Balance0..1OBReadTransaction1/Data/Transaction/BalanceSet of elements used to define the balance as a numerical representation of the net increases and decreases in an account after a transaction entry is applied to the account.OBTransactionCashBalance

Amount1..1OBReadTransaction1/Data/Transaction/Balance/AmountAmount of money of the cash balance after a transaction entry is applied to the account..ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1

OBReadTransaction1/Data/Transaction/

Balance/Amount/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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
CreditDebitIndicator1..1

OBReadTransaction1/Data/Transaction

/Balance/CreditDebitIndicator

Indicates whether the balance is a credit or a debit balance.
Usage: A zero balance is considered to be a credit balance.
OBCreditDebitCodeCredit
Debit

Type1..1

OBReadTransaction1/Data/Transaction/

Balance/Type

Balance type, in a coded form.OBBalanceType1CodeClosingAvailable
ClosingBooked
Expected
ForwardAvailable
Information
InterimAvailable
InterimBooked
OpeningAvailable
OpeningBooked
PreviouslyClosedBooked

MerchantDetails0..1

OBReadTransaction1/Data/Transaction/

MerchantDetails

Details of the merchant involved in the transaction.OBMerchantDetails1

MerchantName0..1

OBReadTransaction1/Data/Transaction/

MerchantDetails/MerchantName

Name by which the merchant is known.Max350Text

MerchantCategoryCode0..1

OBReadTransaction1/Data/Transaction/

MerchantDetails/MerchantCategoryCode

Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.Min3Max4Text

Data Payload - Enumerations

This section gives the definitions for enumerations used in the Account Info APIs.

Code ClassName Definition 
OBBalanceType1CodeClosingAvailable Closing balance of amount of money that is at the disposal of the account owner on the date specified. 
OBBalanceType1CodeClosingBooked 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. 
OBBalanceType1CodeExpected 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. 
OBBalanceType1CodeForwardAvailable Forward available balance of money that is at the disposal of the account owner on the date specified. 
OBBalanceType1CodeInformation Balance for informational purposes. 
OBBalanceType1CodeInterimAvailable 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. 
OBBalanceType1CodeInterimBooked 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. 
OBBalanceType1CodeOpeningAvailable Opening balance of amount of money that is at the disposal of the account owner on the date specified. 
OBBalanceType1CodeOpeningBooked Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. 
OBBalanceType1CodePreviouslyClosedBooked 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. 
OBCreditDebitCodeCreditOperation is a credit
OBCreditDebitCodeDebitOperation is a debit
OBEntryStatus1CodeBookedBooked 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.
OBEntryStatus1CodePendingBooking 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.
OBExternalAccountIdentification2CodeIBANAn identifier used internationally by financial institutions to uniquely identify the account of a customer at a financial institution, as described in the latest edition of the international standard ISO 13616. "Banking and related financial services - International Bank Account Number (IBAN)".
OBExternalAccountIdentification2CodeSortCodeAccountNumberSort Code and Account Number - identifier scheme used in the UK by financial institutions to identify the account of a customer. The identifier is the concatenation of the 6 digit UK sort code and 8 digit account number.
The regular expression for this identifier is: ^[0-9]{6}[0-9]{8}$
OBExternalDirectDebitStatus1CodeActiveThe direct debit mandate is active.
OBExternalDirectDebitStatus1CodeInactiveThe direct debit mandate is inactive.
OBExternalFinancialInstitutionIdentification2CodeBICFIValid BICs for financial institutions are registered by the ISO 9362 Registration Authority in the BIC directory, and consist of eight (8) or eleven (11) contiguous characters.
OBExternalLimitType1CodePre-AgreedThe amount of an arranged lending limit that has been agreed with the account holder
OBExternalLimitType1CodeTemporaryThe amount of a temporary lending limit that has been agreed with the account holder
OBExternalLimitType1CodeEmergencyThe amount of an arranged lending limit that can be borrowed on top of pre-agreed lending, that has been agreed with the account holder.
OBExternalPermissions1CodeReadAccountsBasicPermission to read basic account information.
OBExternalPermissions1CodeReadAccountsDetailAccess to additional elements in the account payload.
OBExternalPermissions1CodeReadBalancesPermission to read all balance information.
OBExternalPermissions1CodeReadBeneficiariesBasicPermission to read basic beneficiary details.
OBExternalPermissions1CodeReadBeneficiariesDetailAccess to additional elements in the beneficiaries payload.
OBExternalPermissions1CodeReadDirectDebitsPermission to read all direct debit information.
OBExternalPermissions1CodeReadStandingOrdersBasicPermission to read standing order information.
OBExternalPermissions1CodeReadStandingOrdersDetailAccess to additional elements in the standing-orders payload.
OBExternalPermissions1CodeReadTransactionsBasicPermission to read basic transaction information.
OBExternalPermissions1CodeReadTransactionsDetailAccess to additional elements in the transactions payload.
OBExternalPermissions1CodeReadTransactionsCreditsAccess to only credit transactions.
OBExternalPermissions1CodeReadTransactionsDebitsAccess to only debit transactions.
OBExternalPermissions1CodeReadProductsPermission to read all product information.
OBExternalProductType1CodeBCABusiness Current Account
OBExternalProductType1CodePCAPersonal Current Account
OBExternalRequestStatus1CodeAuthorisedThe account request has been successfully authorised.
OBExternalRequestStatus1CodeAwaitingAuthorisationThe account request is awaiting further authorisation.
OBExternalRequestStatus1CodeRejectedThe account request has been rejected.
OBExternalRequestStatus1CodeRevokedThe account request has been revoked via the ASPSP interface.

Mapping to Schemes & Standards

ISO 20022

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:

  • The camt.052 header section and trailer sections have been removed - as these are not required for a RESTful API
  • Resources have been identified, and payload structures have been designed for these resources - rather than a full message (i.e., camt.052) that encompasses all resources in a report format. This has meant we've designed separate endpoints and payloads to cover:
    • accounts
    • balances
    • beneficiaries
    • direct-debits
    • products
    • standing-orders
    • transactions
  • Only fields required for the v1.0 scope of the Account Info APIs have been included in the design. 
  • New payloads have been designed for beneficiaries, direct-debits, standing-orders, and products resources - as these are not in the ISO 20022 standard (or the camt.052 message)
  • A DateTime element has been used instead of a complex choice element of Date and DateTime (across all API endpoints). Where time elements do not exist in ASPSP systems - the expectation is the time portion of the DateTime element will be defaulted to 00:00:00+00:00
  • Variations for the accounts structure include: 
    • Standardised inline with the Payment API account structures
    • Contains elements to identify an account Nickname, SecondaryIdentification
  • Variations for the balances structure include:
    • Adding a Type into the CreditLine section - to allow for multiple credit line types affecting the available balance
    • DateTime element has been specified instead of a complex choice of Date and DateTime
  • 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

Usage Examples

No additional Sequence Diagrams are given for the Usage Examples - as they do not differ from the Sequence Diagram in the Overview.

All Permissions Granted

This set of payload examples is for an AISP:

  • Setting up an account-request
  • Getting the status of an account-request
  • Retrieving data from each of the Account Info API endpoints
  • Deleting the account-request

In this scenario:

  • All permissions have been granted to access all Account Info API resources

Setup Account Request

  1. Extended HTTP Headers section to clarify Request and Response Headers
Timezone offsets of -00:00 are not permitted in ISO-8601.
  • Update the examples

Request

Code Block
languagejs
themeMidnight
titlePost Account Requests Request
linenumberstrue
POST /account-requests HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
  "Data": {
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail"
    ],
    "ExpirationDateTime": "2017-05-02T00:00:00+00:00",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00"
  },
  "Risk": {}
}


Response

Code Block
languagejs
themeMidnight
titlePost Account Requests Response
linenumberstrue
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "88379",
    "Status": "AwaitingAuthorisation",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Status - AwaitingAuthorisation

This is an example of a GET request which is made before the account request resource is authorised. 

Request

Code Block
languagejs
themeMidnight
titleGet Account Requests Request
linenumberstrue
GET /account-requests/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Account Requests Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "88379",
    "Status": "AwaitingAuthorisation",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Status - Authorised

This is an example of a GET request which is made after the account request resource is authorised.

Request

Code Block
languagejs
themeMidnight
titleGet Account Requests Request
linenumberstrue
GET /account-requests/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Account Requests Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "88379",
    "Status": "Authorised",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}


Accounts - Bulk

The call to GET /accounts is the first step after an account-request is authorised.

This will allow the AISP to discover which accounts (and AccountId values) are associated with the authorisation of consent.

In this scenario AccountId 22289 has a building society roll number; and AccountId 31820 does not.

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Request
linenumberstrue
GET /accounts HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Accounts Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "GBP",
        "Nickname": "Bills",
        "Account": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200110203345",
          "Name": "Mr Kevin",
          "SecondaryIdentification": "00021"
        }
      },
      {
        "AccountId": "31820",
        "Currency": "GBP",
        "Nickname": "Household",
        "Account": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200110203348",
          "Name": "Mr Kevin"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Accounts - Specific Account

An AISP can also retrieve the account resource details specifically for AccountId 22289

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Request
linenumberstrue
GET /accounts/22289 HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Accounts Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "GBP",
        "Nickname": "Bills",
        "Account": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200110203345",
          "Name": "Mr Kevin",
          "SecondaryIdentification": "00021"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Balances - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Account Balances Request
linenumberstrue
GET /accounts/22289/balances HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Account Balances Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Balance": [
      {
        "AccountId": "22289",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "InterimAvailable",
        "DateTime": "2017-04-05T10:43:07+00:00",
        "CreditLine": [
          {
            "Included": true,
            "Amount": {
              "Amount": "1000.00",
              "Currency": "GBP"
            },
            "Type": "Pre-Agreed"
          }
        ]
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/balances/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Balances - Bulk

Request

Code Block
languagejs
themeMidnight
titleGet Balances Request
linenumberstrue
GET /balances HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Balances Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Balance": [
      {
        "AccountId": "22289",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "InterimAvailable",
        "DateTime": "2017-04-05T10:43:07+00:00",
        "CreditLine": [
          {
            "Included": true,
            "Amount": {
              "Amount": "1000.00",
              "Currency": "GBP"
            },
            "Type": "Pre-Agreed"
          }
        ]
      },
      {
        "AccountId": "31820",
        "Amount": {
          "Amount": "57.36",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Debit",
        "Type": "InterimBooked",
        "DateTime": "2017-05-02T14:22:09+00:00"
      }
    ]
  },
  "Links": {
    "Self": "/balances/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Beneficiaries - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Account Beneficiaries Request
linenumberstrue
GET /accounts/22289/beneficiaries HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Account Beneficiaries Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Beneficiary": [
      {
        "AccountId": "22289",
        "BeneficiaryId": "Ben1",
        "Reference": "Towbar Club",
        "CreditorAccount": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200112345678",
          "Name": "Mrs Juniper"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/beneficiaries/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Beneficiaries - Bulk

GET /beneficiaries

Code Block
languagejs
themeMidnight
titleGet Beneficiaries Request
linenumberstrue
GET /beneficiaries HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


GET /beneficiaries Response

Code Block
languagejs
themeMidnight
titleGet Beneficiaries Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Beneficiary": [
      {
        "AccountId": "22289",
        "BeneficiaryId": "Ben1",
        "Reference": "Towbar Club",
        "CreditorAccount": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200112345678",
          "Name": "Mrs Juniper"
        }
      },
      {
        "AccountId": "31820",
        "BeneficiaryId": "Ben37",
        "Reference": "Golf Club",
        "CreditorAccount": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "87562298675421",
          "Name": "Mr Large"
        }
      }
    ]
  },
  "Links": {
    "Self": "/beneficiaries/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Direct Debits - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Direct Debits Request
linenumberstrue
GET /accounts/22289/direct-debits HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json



Response

Code Block
languagejs
themeMidnight
titleGet Accounts Direct Debits Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "DirectDebit": [
      {
        "AccountId": "22289",
        "DirectDebitId": "DD03",
        "MandateIdentification": "Caravanners",
        "DirectDebitStatusCode": "Active",
        "Name": "Towbar Club 3 - We Love Towbars",
        "PreviousPaymentDateTime": "2017-04-05T10:43:07+00:00",
        "PreviousPaymentAmount": {
          "Amount": "0.57",
          "Currency": "GBP"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}


Direct Debits - Bulk

Request

Code Block
languagejs
themeMidnight
titleGet Direct Debits Request
linenumberstrue
GET /direct-debits HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Direct Debits Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "DirectDebit": [
      {
        "AccountId": "22289",
        "DirectDebitId": "DD03",
        "MandateIdentification": "Caravanners",
        "DirectDebitStatusCode": "Active",
        "Name": "Towbar Club 3 - We Love Towbars",
        "PreviousPaymentDateTime": "2017-04-05T10:43:07+00:00",
        "PreviousPaymentAmount": {
          "Amount": "0.57",
          "Currency": "GBP"
        }
      },
      {
        "AccountId": "31820",
        "DirectDebitId": "DD77",
        "MandateIdentification": "Golfers",
        "DirectDebitStatusCode": "Active",
        "Name": "Golf Club",
        "PreviousPaymentDateTime": "2017-05-06T09:00:00+00:00",
        "PreviousPaymentAmount": {
          "Amount": "22.30",
          "Currency": "GBP"
        }
      }
    ]
  },
  "Links": {
    "Self": "/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Product  - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Product Request
linenumberstrue
GET /accounts/22289/product HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Accounts Product Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Product": [
      {
        "AccountId": "22289",
        "ProductIdentifier": "51B",
        "ProductType": "PCA",
        "ProductName": "321 Product"
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/product"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Products - Bulk

Request

Code Block
languagejs
themeMidnight
titleGet Products Request
linenumberstrue
GET /products HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Products Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Product": [
      {
        "AccountId": "22289",
        "ProductIdentifier": "51B",
        "ProductType": "PCA",
        "ProductName": "321 Product"
      },
      {
        "AccountId": "31820",
        "ProductIdentifier": "001",
        "ProductType": "BCA",
        "ProductName": "123 Product"
      }
    ]
  },
  "Links": {
    "Self": "/products/"
  },
  "Meta": {
    "TotalPages": 1
  }
}


Standing Orders - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Standing Orders Request
linenumberstrue
GET /accounts/22289/standing-orders HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Accounts Standing Orders Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "StandingOrder": [
      {
        "AccountId": "22289",
        "StandingOrderId": "Ben3",
        "Frequency": "EvryWorkgDay",
        "Reference": "Towbar Club 2 - We Love Towbars",
        "FirstPaymentDateTime": "2017-08-12T00:00:00+00:00",
        "FirstPaymentAmount": {
          "Amount": "0.57",
          "Currency": "GBP"
        },
        "NextPaymentDateTime": "2017-08-13T00:00:00+00:00",
        "NextPaymentAmount": {
          "Amount": "0.56",
          "Currency": "GBP"
        },
        "FinalPaymentDateTime": "2027-08-12T00:00:00+00:00",
        "FinalPaymentAmount": {
          "Amount": "0.56",
          "Currency": "GBP"
        },
        "CreditorAccount": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200112345678",
          "Name": "Mrs Juniper"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/standing-orders/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Standing Orders - Bulk

Request

Code Block
languagejs
themeMidnight
titleGet Standing Orders Request
linenumberstrue
GET /standing-orders HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Standing Orders Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmDisIsDaW1nt3r0fRDis
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "StandingOrder": [
      {
        "AccountId": "22289",
        "StandingOrderId": "Ben3",
        "Frequency": "EvryWorkgDay",
        "Reference": "Towbar Club 2 - We Love Towbars",
        "FirstPaymentDateTime": "2017-08-12T00:00:00+00:00",
        "FirstPaymentAmount": {
          "Amount": "0.57",
          "Currency": "GBP"
        },
        "NextPaymentDateTime": "2017-08-13T00:00:00+00:00",
        "NextPaymentAmount": {
          "Amount": "0.56",
          "Currency": "GBP"
        },
        "FinalPaymentDateTime": "2027-08-12T00:00:00+00:00",
        "FinalPaymentAmount": {
          "Amount": "0.56",
          "Currency": "GBP"
        },
        "CreditorAccount": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "80200112345678",
          "Name": "Mrs Juniper"
        }
      },
      {
        "AccountId": "22289",
        "StandingOrderId": "Ben5",
        "Frequency": "WkinMnthDay(2)",
        "Reference": "Golf - We Love Golf",
        "FirstPaymentDateTime": "2017-06-12T00:00:00+00:00",
        "FirstPaymentAmount": {
          "Amount": "23.00",
          "Currency": "GBP"
        },
        "NextPaymentDateTime": "2017-07-12T00:00:00+00:00",
        "NextPaymentAmount": {
          "Amount": "23.00",
          "Currency": "GBP"
        },
        "FinalPaymentDateTime": "2018-06-12T00:00:00+00:00",
        "FinalPaymentAmount": {
          "Amount": "23.00",
          "Currency": "GBP"
        },
        "CreditorAccount": {
          "SchemeName": "SortCodeAccountNumber",
          "Identification": "23605490179017",
          "Name": "Mr Tee"
        }
      }
    ]
  },
  "Links": {
    "Self": "/standing-orders/"
  },
  "Meta": {
    "TotalPages": 1
  }
}


Transactions - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Account Transactions Request
linenumberstrue
GET /accounts/22289/transactions HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Account Transactions Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Transaction": [
      {
        "AccountId": "22289",
        "TransactionId": "123",
        "TransactionReference": "Ref 1",
        "Amount": {
          "Amount": "10.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Status": "Booked",
        "BookingDateTime": "2017-04-05T10:43:07+00:00",
        "ValueDateTime": "2017-04-05T10:45:22+00:00",
        "TransactionInformation": "Cash from Aubrey",
        "BankTransactionCode": {
          "Code": "ReceivedCreditTransfer",
          "SubCode": "DomesticCreditTransfer"
        },
        "ProprietaryBankTransactionCode": {
          "Code": "Transfer",
          "Issuer": "AlphaBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "230.00",
            "Currency": "GBP"
          },
          "CreditDebitIndicator": "Credit",
          "Type": "InterimBooked"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/transactions/"
  },
  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}


Transactions - Bulk

None of the transactions included in the payload are Ecommerce transactions - so MerchantDetails are not included in the examples.

Request

Code Block
languagejs
themeMidnight
titleGet Transactions Request
linenumberstrue
GET /transactions HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Transactions Response
linenumberstrue
HTTP/1.1 200 OK 
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Transaction": [
      {
        "AccountId": "22289",
        "TransactionId": "123",
        "TransactionReference": "Ref 123",
        "Amount": {
          "Amount": "10.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Status": "Booked",
        "BookingDateTime": "date",
        "ValueDateTime": "2017-04-05T10:45:22+00:00",
        "TransactionInformation": "Cash from Aubrey",
        "BankTransactionCode": {
          "Code": "ReceivedCreditTransfer",
          "SubCode": "DomesticCreditTransfer"
        },
        "ProprietaryBankTransactionCode": {
          "Code": "Transfer",
          "Issuer": "AlphaBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "230.00",
            "Currency": "GBP"
          },
          "CreditDebitIndicator": "Credit",
          "Type": "InterimBooked"
        }
      },
      {
        "AccountId": "31820",
        "TransactionId": "567",
        "TransactionReference": "Ref 124",
        "Amount": {
          "Amount": "100.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Debit",
        "Status": "Booked",
        "BookingDateTime": "2017-05-02T14:22:09+00:00",
        "ValueDateTime": "2017-05-02T14:22:09+00:00",
        "TransactionInformation": "Paid the gas bill",
        "AddressLine": "Coventry",
        "BankTransactionCode": {
          "Code": "IssuedCreditTransfer",
          "SubCode": "AutomaticTransfer"
        },
        "ProprietaryBankTransactionCode": {
          "Code": "DirectDebit",
          "Issuer": "AlphaBank"
        },
        "Balance": {
          "Amount": {
            "Amount": "57.36",
            "Currency": "GBP"
          },
          "CreditDebitIndicator": "Debit",
          "Type": "InterimBooked"
        }
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/transactions/"
  },
  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}



Delete Account Request

The DELETE /account-requests call allows an AISP to delete a previously created account-request (whether it is currently authorised or not). The PSU may want to remove their consent via the AISP instead of revoking authorisation with the ASPSP.

This API call allows the PSU to revoke consent with the AISP - and for that consent to be reflected in authorisation with the ASPSP.

Request

Code Block
languagejs
themeMidnight
titleDelete Account Requests Request
linenumberstrue
DELETE /account-requests/88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d


Response

Code Block
languagejs
themeMidnight
titleDelete Account Requests Response
linenumberstrue
HTTP/1.1 204 No Content
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d



Limited Permissions Granted

This set of payload examples is for an AISP:

  • Setting up an account-request
  • Retrieving data from:
    • /accounts/{AccountId}/balances
    • /accounts/{AccountId}/transactions

In this scenario:

  • Only ReadAccountsBasic and ReadBalances permissions have been requested

Setup Account Request

Request

Code Block
languagejs
themeMidnight
titlePost Account Requests Request
linenumberstrue
POST /account-requests HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
  "Data": {
    "Permissions": [
      "ReadAccountsBasic",
      "ReadBalances"
    ],
    "ExpirationDateTime": "2017-05-02T00:00:00+00:00",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00"
  },
  "Risk": {}
}


Response

Code Block
languagejs
themeMidnight
titlePost Account Requests Response
linenumberstrue
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "88379",
    "Status": "AwaitingAuthorisation",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsBasic",
      "ReadBalances"
    ],
    "ExpirationDateTime": "2017-08-02T00:00:00+00:00",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "/account-requests/88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Accounts - Bulk

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Request
linenumberstrue
GET /accounts HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Accounts Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "GBP",
        "Nickname": "Bills"
      }
    ]
  },
  "Links": {
    "Self": "/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Balances - Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Account Balances Request
linenumberstrue
GET /accounts/22289/balances HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGet Account Balances Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Balance": [
      {
        "AccountId": "22289",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "InterimAvailable",
        "DateTime": "2017-04-05T10:43:07+00:00",
        "CreditLine": [
          {
            "Included": true,
            "Amount": {
              "Amount": "1000.00",
              "Currency": "GBP"
            },
            "Type": "Pre-Agreed"
          }
        ]
      }
    ]
  },
  "Links": {
    "Self": "/accounts/22289/balances/"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Transactions - Specific Account

In this example - the AISP does not have access to call the transactions endpoint. This will result in a 403 error.

Request

Code Block
languagejs
themeMidnight
titleGET Account Transactions Request
linenumberstrue
GET /accounts/22289/transactions HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Response

Code Block
languagejs
themeMidnight
titleGET Account Transactions Response
linenumberstrue
HTTP/1.1 403 Forbidden 
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d


Pagination

The example below illustrates how an ASPSP may return a paginated response. 

Request

Code Block
languagejs
themeMidnight
titlePaginated Transaction Request
linenumberstrue
GET /accounts/22289/transactions HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Paginated Resource Response

Code Block
languagejs
themeMidnight
titlePaginated Transaction Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    ...
  },
  "Links": {
    "Self": "/accounts/22289/transactions/",
    "Last": "/accounts/22289/transactions?pg=20",    
	"First": "/accounts/22289/transactions/",    
	"Next": "/accounts/22289/transactions?pg=2"
  },
  "Meta": {
    "TotalPages": 20,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}


The AISP can follow the links provided in the Links section of the payload to navigate to the first, last, next and previous pages:

Request Next Page of Results

Code Block
languagejs
themeMidnight
titlePaginated Transaction Request (Next)
linenumberstrue
GET /accounts/22289/transactions?pg=2 HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


Paginated Resource Response

Code Block
languagejs
themeMidnight
titlePaginated Transaction Response
linenumberstrue
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    ...
  },
  "Links": {
    "Self": "/accounts/22289/transactions?pg=2",
    "Last": "/accounts/22289/transactions?pg=20",    
	"First": "/accounts/22289/transactions/",    
	"Next": "/accounts/22289/transactions?pg=3",
	"Prev": "/accounts/22289/transactions?pg=1"
  },
  "Meta": {
    "TotalPages": 20,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }
}


Alternate and Error Flows

Missing or Expired Access Token

This flow assumes that the following Steps have been completed successfully:

  • Step 1: Request Account Information
  • Step 2: Setup Account Request
  • Step 3: Authorize Consent

The AISP attempts to provide an expired or missing access token to the ASPSP in an attempt to Request Data

Code Block
titleMissing or Expired Access Token
collapsetrue
participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
 

alt Request data with a missing or expired access-token
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: GET /accounts
ASPSP Resource Server -> AISP: HTTP 401 (Unauthorized)
 
 
AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions
ASPSP Resource Server -> AISP: HTTP 401 (Unauthorized)
 

end alt

Incomplete or Malformed Request Payload

This flow assumes that the following Steps have been completed successfully:

  • Step 1: Request Account Information
  • Step 2: Setup Account Request
  • Step 3: Authorize Consent

The AISP provides a malformed request to the ASPSP in an attempt to setup an Account Request.

Code Block
titleIncomplete or Malformed Request
collapsetrue
participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
 

alt AISP attempts to setup an account request with a malformed payload
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: POST /account-requests
ASPSP Resource Server -> AISP: HTTP 400 (Bad Request)
 
end alt

Missing or Invalid Access Token Scope

This flow assumes that the following Steps have been completed successfully:

  • Step 1: Request Account Information
  • Step 2: Setup Account Request
  • Step 3: Authorize Consent

The AISP provides a (valid) access token which does not have a valid scope (or link to the correct Permissions) to Request Data

Code Block
titleMissing or Invalid Access Token Scope
collapsetrue
participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
 

alt Request data with a missing or invalid access-token scope
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: GET /accounts
ASPSP Resource Server -> AISP: HTTP 403 (Forbidden)
 
 
AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions
ASPSP Resource Server -> AISP: HTTP 403 (Forbidden)
 

end alt

Sudden Burst of API Requests

This flow assumes that the following Steps have been completed successfully:

  • Step 1: Request Account Information
  • Step 2: Setup Account Request
  • Step 3: Authorize Consent

The AISP provides a (valid) access token which is used to generate a burst of multiple requests to retrieve an Accounts resource.

The ASPSP can optionally choose to return a 429 Response

Code Block
titleSudden Burst of API Requests
collapsetrue
participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
 
alt AISP attempts to retrieve an Account Resource
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
    loop Burst of multiple GET requests
        AISP -> ASPSP Resource Server: GET /accounts/{AccountId}
        opt
            ASPSP Resource Server -> AISP: HTTP 429 (Too Many Requests)
        end
    end
end

Failed Authorisation Consent

This flow assumes that the following Steps have been completed successfully:

  • Step 1: Request Account Information
  • Step 2: Setup Account Request

The Step 3: Authorize Consent Flow fails to succeed due to the PSU providing invalid credentials to the ASPSP, resulting in no Authorization Code being generated.

Code Block
titleFailed Authorization Consent
collapsetrue
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 request
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-requests
ASPSP Resource Server -> AISP: HTTP 201 (Created), AccountRequestId
AISP -> PSU: HTTP 302 (Found), Redirect (AccountRequestId)
 
note over PSU, ASPSP Resource Server
Step 3: Failed authorise consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (AccountRequestId)
PSU -> ASPSP Authorisation Server: Invalid Credentials
ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (error)
PSU -> AISP: Follow redirect (error)
AISP -> PSU : Error Response