Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 23 Jun 2017 | Open Banking Read/Write API Team | This is the Baseline version. No Changes from v1.0 RC4. |
This specification describes the Account Information and Transaction API flows and payloads.
The API endpoints described here allow an AISP to:
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.
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 OBIE principles for developing the new API standards:
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:
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).
The Account Information and Transaction APIs will not be idempotent for v1.0.
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 section will only be applicable if the policy decision is to implement non-repudiation through digital signatures. |
The APIs will provide non-repudiation through digital signatures.
The specifications required to achieve this are described in Basics / Non-repudiation.
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:
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.
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.
This v1.0 specification does not cater for:
The figure below provides a general outline of a account information requests and flow using the Account Info APIs.
Step 1: Request Account Information
Step 2: Setup Account Request
Step 3: Authorise Consent
Step 4: Request Data
participant PSU participant AISP participant ASPSP Authorisation Server participant ASPSP Resource Server note over PSU, ASPSP Resource Server Step 1: Request account information end note PSU -> AISP: Get account/transaction information note over PSU, ASPSP Resource Server Step 2: Setup account 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 AISP-> PSU: HTTP 200 (OK), List of transactions |
Actor | Abbreviation | Type | Specializes | Description |
---|---|---|---|---|
Payment Service User | PSU | Person | N/A | A natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10)) |
Payment Service Provider | PSP | Legal Entity | N/A | A legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11) |
Account Servicing Payment Service Provider | ASPSP | Legal Entity | PSP | 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 Parties | TPP | Legal Entity | PSP | 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 Provider | PISP | Legal Entity | TPP | 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 | AISP | Legal Entity | TPP | A TPP that provides Account Information Services. Again, PSD2 defines AISPs in Article 4(19) circularly as a PSP that provides account information services |
The following headers SHOULD be inserted by the TPP in each API call:
Header Value | Notes | POST | GET | DELETE |
---|---|---|---|---|
x-fapi-financial-id | The unique id of the ASPSP to which the request is issued. The unique id will be issued by OB. | Mandatory | Mandatory | Mandatory |
x-fapi-customer-last-logged-time | The time when the PSU last logged in with the TPP. | Optional | Optional | Optional |
x-fapi-customer-ip-address | The PSU's IP address if the PSU is currently logged in with the TPP. | Optional | Optional | Optional |
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. | Optional | Optional | Optional |
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. | Mandatory | Mandatory | Mandatory |
Content-Type | Standard HTTP Header; Represents the format of the payload being provided in the request. This must be set to application/json. | Mandatory | Do not use | Do 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. | Optional | Optional | Optional |
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. | TBC | TBC | TBC |
(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:
Header Value | Notes | Mandatory ? |
---|---|---|
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. | TBC |
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 |
The following are the HTTP response codes for the different HTTP methods - across all Account Info API endpoints.
Situation | HTTP Status | Notes | Returned by POST | Returned by GET | Returned by DELETE |
---|---|---|---|---|---|
Query completed successfully | 200 OK | No | Yes | No | |
Normal execution. The request has succeeded. | 201 Created | The operation results in the creation of a new resource. | Yes | No | No |
Delete operation completed successfully | 204 No Content | No | No | Yes | |
Account Request has malformed, missing or non-compliant JSON body or URL parameters | 400 Bad Request | The requested operation will not be carried out. | Yes | No | No |
Authorization header missing or invalid token | 401 Unauthorized | The operation was refused access. | Yes | Yes | Yes |
Token invalid, has incorrect scope or a security policy was violated | 403 Forbidden | The operation was refused access. | Yes | Yes | Yes |
The operation was refused as too many requests have been made within a certain timeframe. | 429 Too Many Requests | Throttling is a NFR. | Yes | Yes | Yes |
Something went wrong on the API gateway or micro-service | 500 Internal Server Error | The operation failed. | Yes | Yes | Yes |
An ASPSP MAY return other standard HTTP status codes (e.g. from gateways and other edge devices) as described in RFC 7231 - Section 6.
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:
Situation | Request | Response |
---|---|---|
TPP attempts to retrieve an account with an AccountId that does not exist | GET /accounts/1001 | 400 (Bad Request) |
TPP attempts to retrieve a resource that is not defined | GET /credit-cards | 404 (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-debits | 404 (Not Found) |
TPP attempts to retrieve standing orders for an AccountId that does not exists | GET /accounts/1001/standing-orders | 400 (Bad Request) |
TPP attempts to retrieve standing orders for an AccountId that exists, but does not have any standing orders | GET /accounts/1000/standing-orders | 200 OK { "Data": { "StandingOrder": [] }, "Links": { "self": "/accounts/1000/standing-orders/" }, "Meta": { "total-pages": 1 } } |
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:
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 following pre-conditions must be satisfied in order to use these APIs:
The API for creating an account-request resource is not idempotent. Once 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.
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 section will only be applicable if the policy decision is to implement non-repudiation through digital signatures. |
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.
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.
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.
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. |
http://openbanking.org.uk/iat | This must be a string containing a timestamp in ISO 8601 format. 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. |
The signer must compute the signature as a detached JWS as defined in RFC 7515.
payload = base64Encode (JOSEHeader) + "." + base64Encode( json) detachedJWS = base64Encode( JOSEHeader) + ".." + base64Encode ( encrypt (privateKey, base64Encode(json))) |
The signer must include an HTTP header called x-jws-signature with its value set to the signature computed in Step 3.
x-jws-signature: V2hhdCBoYXRoIGdvZCB3cm91Z2h0ID8=..QnkgR2VvcmdlLCBzaGUncyBnb3QgaXQhIEJ5IEdlb3JnZSBzaGUncyBnb3QgaXQhIE5vdyBvbmNlIGFnYWluLCB3aGVyZSBkb2VzIGl0IHJhaW4/ |
The verifier must extract and decode the JOSE header and signature from the JWS provided in the x-jws-signature http header
JWSParts[] = detachedJWS.tokenize(".."); JOSEHeader = base64Decode (JWSParts[0]); Signature = JWSParts[1]; ExpectedSignedPayload = JWSParts[0] + "." + base64Encode( httpBody) |
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.
The verifier must verify the signature by decrypting it and ensuring that it matches the ExpectedSignedPayload.
DecryptedPayload = base64Decode ( decrypt ( publicKey, Signature)); |
{ "alg": "", "kid": "90210ABAD", "b64": false, "http://openbanking.org.uk/iat": "2017-06-12T20:05:50+00:00", "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"] ] |
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:
In the above situations, the ASPSP must return data for the remaining valid period specified by the filter.
// 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 |
An ASPSP MAY provide a paginated response for GET operations that return multiple records.
In such a situation, the ASPSP MUST:
Additionally, the ASPSP MAY provide:
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.
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. |
- 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.- 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 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.
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".
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:
Resource | HTTP Operation | Endpoint | Mandatory ? | Scope | Idempotent | Parameters | Request Object | Response Object | |
---|---|---|---|---|---|---|---|---|---|
1 | account-requests | POST | POST /account-requests | Mandatory | accounts | No | Pagination | OBReadRequest1 | OBReadResponse1 |
2 | account-requests | GET | GET /account-requests/{AccountRequestId} | Optional | accounts | Pagination | OBReadResponse1 | ||
3 | account-requests | DELETE | DELETE /account-requests/{AccountRequestId} | Mandatory | accounts | Yes | Pagination | ||
4 | accounts | GET | GET /accounts | Mandatory | accounts | Pagination | OBReadAccount1 | ||
5 | accounts | GET | GET /accounts/{AccountId} | Mandatory | accounts | Pagination | OBReadAccount1 | ||
6 | balances | GET | GET /accounts/{AccountId}/balances | Mandatory | accounts | Pagination | OBReadBalance1 | ||
7 | beneficiaries | GET | GET /accounts/{AccountId}/beneficiaries | Mandatory | accounts | Pagination | OBReadBeneficiary1 | ||
8 | direct-debits | GET | GET /accounts/{AccountId}/direct-debits | Mandatory | accounts | Pagination | OBReadDirectDebit1 | ||
9 | products | GET | GET /accounts/{AccountId}/product | Mandatory | accounts | Pagination | OBReadProduct1 | ||
10 | standing-orders | GET | GET /accounts/{AccountId}/standing-orders | Mandatory | accounts | Pagination | OBReadStandingOrder1 | ||
11 | transactions | GET | GET /accounts/{AccountId}/transactions | Mandatory | accounts | Pagination Filtering | OBReadTransaction1 | ||
12 | balances | GET | GET /balances | Optional | accounts | Pagination | OBReadBalance1 | ||
13 | beneficiaries | GET | GET /beneficiaries | Optional | accounts | Pagination | OBReadBeneficiary1 | ||
14 | direct-debits | GET | GET /direct-debits | Optional | accounts | Pagination | OBReadDirectDebit1 | ||
15 | products | GET | GET /products | Optional | accounts | Pagination | OBReadProduct1 | ||
16 | standing-orders | GET | GET /standing-orders | Optional | accounts | Pagination | OBReadStandingOrder1 | ||
17 | transactions | GET | GET /transactions | Optional | accounts | 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 |
The API allows the AISP to ask an ASPSP to create a new account-request resource.
The account-request resource that is created successfully must have one of the following Status code-list enumerations:
Status | Status Description | |
---|---|---|
1 | Rejected | The account request has been rejected. |
2 | AwaitingAuthorisation | The account request is awaiting authorisation. |
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.
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:
Status | Status Description | |
---|---|---|
1 | Rejected | The account request has been rejected. |
2 | AwaitingAuthorisation | The account request is awaiting authorisation. |
3 | Authorised | The account request has been successfully authorised. |
4 | Revoked | The account request has been revoked via the ASPSP interface. |
DELETE /account-requests/{AccountRequestId} |
If the PSU revokes consent to data access with the AISP - the AISP should delete the account-request resource.
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 /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 /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.
The access tokens required for accessing the Account Info APIs must have at least the following scope:
accounts |
AISPs must use a client credentials grant to obtain a token to access the account-requests resource.
AISPs must use a authorization code grant to obtain a token to access all other resources.
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).
A 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:
Once these steps are complete, the consent is considered to have been authorised by the PSU.
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 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:
Permissions | Endpoints | Business Logic | Data Cluster Description |
---|---|---|---|
ReadAccountsBasic | /accounts /accounts/{AccountId} | Ability to read basic account information | |
ReadAccountsDetail | /accounts /accounts/{AccountId} | Access to additional elements in the payload (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 payload | Ability to read account identification details for the beneficiary |
ReadDirectDebits | /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 payload | Ability to read account identification details for beneficiary of the standing order |
ReadTransactionsBasic | /transactions /accounts/{AccountId}/transactions | Permissions must also include at least one of:
| 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
| 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:
| Ability to read only credit transactions |
ReadTransactionsDebits | /transactions /accounts/{AccountId}/transactions | Access to debit transactions. Permissions must also include one of:
| 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 Codes | Data Element Name | Occurrence | XPath |
---|---|---|---|
ReadAccountsDetail | Account | 0..1 | OBReadAccount1/Data/Account/Account |
ReadAccountsDetail | Servicer | 0..1 | OBReadAccount1/Data/Account/Servicer |
ReadBeneficiariesDetail | Servicer | 0..1 | OBReadBeneficiary1/Data/Beneficiary/Servicer |
ReadBeneficiariesDetail | CreditorAccount | 0..1 | OBReadBeneficiary1/Data/Beneficiary/CreditorAccount |
ReadStandingOrderDetail | Servicer | 0..1 | OBReadStandingOrder1/Data/StandingOrder/Servicer |
ReadStandingOrderDetail | CreditorAccount | 0..1 | OBReadStandingOrder1/Data/StandingOrder/CreditorAccount |
ReadTransactionDetail | TransactionInformation | 0..1 | OBReadTransaction1/Data/Transaction/TransactionInformation |
ReadTransactionDetail | Balance | 0..1 | OBReadTransaction1/Data/Transaction/Balance |
ReadTransactionDetail | MerchantDetails | 0..1 | OBReadTransaction1/Data/Transaction/MerchantDetails |
Example behaviour of the Permissions for the ReadAccountsBasic and ReadAccountDetail codes is as follows:
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.
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.
The Account Request resource can have one of the following status codes after authorisation has taken place:
Status | Description | |
---|---|---|
1 | Authorised | The account request has been successfully authorised. |
2 | Rejected | The account request has been rejected. |
3 | Revoked | The account request has been revoked via the ASPSP interface. |
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.
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 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):
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.
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.
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.
Information for risk scoring and assessment will come via:
No fields for business logic security concerns have been identified for the Account Info APIs for v1.0.
The swagger specification for Account Information APIs can be downloaded from the following links:
This section gives an overview of the top level structure for the API payloads for the Account Info APIs.
The top level request structure for Account Info APIs:
{ "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.
The top level response structure for Account Info APIs:
{ "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:
"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" } |
The Meta section is mandatory, but can be empty. An optional member is "total-pages" which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.
For example:
"Meta": { "total-pages": 13 } |
This data dictionary section gives the detail on the payload content for Account Information flow to request access to account information.
The OBReadRequest1 object will be used for the call to:
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes |
---|---|---|---|---|---|
OBReadRequest1 | OBReadRequest1 | OBReadRequest1 | |||
Data | 1..1 | OBReadRequest1/Data | OBReadData1 | ||
Permissions | 1..n | OBReadRequest1/Data/Permissions | Specifies 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. | OBExternalPermissions1Code | ReadAccountsBasic ReadAccountsDetail ReadBalances ReadBeneficiariesBasic ReadBeneficiariesDetail ReadDirectDebits ReadProducts ReadStandingOrdersBasic ReadStandingOrdersDetail ReadTransactionsBasic ReadTransactionsCredits ReadTransactionsDebits ReadTransactionsDetail |
ExpirationDateTime | 0..1 | OBReadRequest1/Data/ExpirationDateTime | Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended. | ISODateTime | |
TransactionFromDateTime | 0..1 | OBReadRequest1/Data/TransactionFromDateTime | Specified 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 | |
TransactionToDateTime | 0..1 | OBReadRequest1/Data/TransactionToDateTime | Specified 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 | |
Risk | 1..1 | OBReadRequest1/Risk | The 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 |
The OBReadResponse1 object will be used for the:
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes |
---|---|---|---|---|---|
OBReadResponse1 | OBReadResponse1 | OBReadResponse1 | |||
Data | 1..1 | OBReadResponse1/Data | OBReadDataResponse1 | ||
AccountRequestId | 1..1 | OBReadResponse1/Data/AccountRequestId | Unique identification as assigned to identify the account request resource. | Max128Text | |
Status | 0..1 | OBReadResponse1/Data/Status | Specifies the status of the account request resource. | OBExternalRequestStatus1Code | Authorised Revoked |
CreationDateTime | 1..1 | OBReadResponse1/Data/CreationDateTime | Date and time at which the resource was created. | ISODateTime | |
Permissions | 1..n | OBReadResponse1/Data/Permissions | Specifies 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. | OBExternalPermissions1Code | ReadAccountsBasic ReadAccountsDetail ReadBalances ReadBeneficiariesBasic ReadBeneficiariesDetail ReadDirectDebits ReadProducts ReadStandingOrdersBasic ReadStandingOrdersDetail ReadTransactionsBasic ReadTransactionsCredits ReadTransactionsDebits ReadTransactionsDetail |
ExpirationDateTime | 0..1 | OBReadResponse1/Data/ExpirationDateTime | Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended. | ISODateTime | |
TransactionFromDateTime | 0..1 | OBReadResponse1/Data/TransactionFromDateTime | Specified 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 | |
TransactionToDateTime | 0..1 | OBReadResponse1/Data/TransactionToDateTime | Specified 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 | |
Risk | 1..1 | OBReadResponse1/Risk | The 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 |
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:
The OBReadAccount1 object will be used for the call to:
The resource that represents the account to which credit and debit entries are made.
Each account resource will have a unique and immutable AccountId.
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadAccount1 | OBReadAccount1 | OBReadAccount1 | ||||
Data | 1..1 | OBReadAccount1/Data | OBReadDataAccount1 | |||
Account | 0..n | OBReadAccount1/Data/Account | Unambiguous identification of the account to which credit and debit entries are made. | OBAccount1 | ||
AccountId | 1..1 | OBReadAccount1/Data/Account/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
Currency | 1..1 | OBReadAccount1/Data/Account/Currency | Identification 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} | |
Nickname | 0..1 | OBReadAccount1/Data/Account/Nickname | The nickname of the account, assigned by the account owner in order to provide an additional means of identification of the account. | Max70Text | ||
Account | 0..1 | OBReadAccount1/Data/Account/Account | Provides the details to identify an account. | OBCashAccount1 | ||
SchemeName | 1..1 | OBReadAccount1/Data/Account/Account/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalAccountIdentification2Code | BBAN IBAN | |
Identification | 1..1 | OBReadAccount1/Data/Account/Account/Identification | Identification assigned by an institution to identify an account. This identification is known by the account owner. | Max34Text | ||
Name | 0..1 | OBReadAccount1/Data/Account/Account/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 | ||
SecondaryIdentification | 0..1 | OBReadAccount1/Data/Account/Account/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 | ||
Servicer | 0..1 | OBReadAccount1/Data/Account/Servicer | Party 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 | ||
SchemeName | 1..1 | OBReadAccount1/Data/Account/Servicer/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalFinancialInstitutionIdentification2Code | BICFI UKSortCode | |
Identification | 1..1 | OBReadAccount1/Data/Account/Servicer/Identification | Unique and unambiguous identification of the servicing institution. | Max35Text |
The OBReadBalance1 object will be used for the call to:
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.
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadBalance1 | OBReadBalance1 | OBReadBalance1 | ||||
Data | 1..1 | OBReadBalance1/Data | OBReadDataBalance1 | |||
Balance | 1..n | OBReadBalance1/Data/Balance | Set of elements used to define the balance details. | OBCashBalance1 | ||
AccountId | 1..1 | OBReadBalance1/Data/Balance/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
Amount | 1..1 | OBReadBalance1/Data/Balance/Amount | Amount of money of the cash balance. | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..1 | OBReadBalance1/Data/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} | |
CreditDebitIndicator | 1..1 | OBReadBalance1/Data/Balance/CreditDebitIndicator | Indicates whether the balance is a credit or a debit balance. Usage: A zero balance is considered to be a credit balance. | OBCreditDebitCode | Credit Debit | |
Type | 1..1 | OBReadBalance1/Data/Balance/Type | Balance type, in a coded form. | OBBalanceType1Code | ClosingAvailable ClosingBooked Expected ForwardAvailable Information InterimAvailable InterimBooked OpeningAvailable OpeningBooked PreviouslyClosedBooked | |
DateTime | 1..1 | OBReadBalance1/Data/Balance/DateTime | Indicates the date (and time) of the balance. | ISODateTime | ||
CreditLine | 0..n | OBReadBalance1/Data/Balance/CreditLine | Set of elements used to provide details on the credit line. | OBCreditLine1 | ||
Included | 1..1 | OBReadBalance1/Data/Balance/CreditLine/Included | Indicates 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 | ||
Amount | 0..1 | OBReadBalance1/Data/Balance/CreditLine/Amount | Amount of money of the credit line. | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..1 | OBReadBalance1/Data/Balance/CreditLine/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} | |
Type | 0..1 | OBReadBalance1/Data/Balance/CreditLine/Type | Limit type, in a coded form. | OBExternalLimitType1Code | Pre-Agreed Emergency Temporary |
The OBReadBeneficiary1 object will be used for the call to:
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:
This is the expected behaviour of the beneficiaries endpoints - in the case an ASPSP manages beneficiaries at a customer level:
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes |
---|---|---|---|---|---|
OBReadBeneficiary1 | OBReadBeneficiary1 | OBReadBeneficiary1 | |||
Data | 1..1 | OBReadBeneficiary1/Data | OBReadDataBeneficiary1 | ||
Beneficiary | 0..n | OBReadBeneficiary1/Data/Beneficiary | OBBeneficiary1 | ||
AccountId | 0..1 | OBReadBeneficiary1/Data/Beneficiary/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | |
BeneficiaryId | 0..1 | OBReadBeneficiary1/Data/Beneficiary/BeneficiaryId | A unique and immutable identifier used to identify the beneficiary resource. This identifier has no meaning to the account owner. | Max40Text | |
Reference | 0..1 | OBReadBeneficiary1/Data/Beneficiary/Reference | Unique 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 | |
Servicer | 0..1 | OBReadBeneficiary1/Data/Beneficiary/Servicer | Party 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 | |
SchemeName | 1..1 | OBReadBeneficiary1/Data/Beneficiary/Servicer/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalFinancialInstitutionIdentification2Code | BICFI UKSortCode |
Identification | 1..1 | OBReadBeneficiary1/Data/Beneficiary/Servicer/Identification | Unique and unambiguous identification of the servicing institution. | Max35Text | |
CreditorAccount | 0..1 | OBReadBeneficiary1/Data/Beneficiary/CreditorAccount | Provides the details to identify the beneficiary account. | OBCashAccount1 | |
SchemeName | 1..1 | OBReadBeneficiary1/Data/Beneficiary/CreditorAccount/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalAccountIdentification2Code | BBAN IBAN |
Identification | 1..1 | OBReadBeneficiary1/Data/Beneficiary/CreditorAccount/Identification | Identification assigned by an institution to identify an account. This identification is known by the account owner. | Max34Text | |
Name | 0..1 | OBReadBeneficiary1/Data/Beneficiary/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 | |
SecondaryIdentification | 0..1 | OBReadBeneficiary1/Data/Beneficiary/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 |
The OBReadDirectDebit1 object will be used for the call to:
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.
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadDirectDebit1 | OBReadDirectDebit1 | OBReadDirectDebit1 | ||||
Data | 1..1 | OBReadDirectDebit1/Data | OBReadDataDirectDebit1 | |||
DirectDebit | 0..n | OBReadDirectDebit1/Data/DirectDebit | Account to or from which a cash entry is made. | OBDirectDebit1 | ||
AccountId | 1..1 | OBReadDirectDebit1/Data/DirectDebit/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
DirectDebitId | 0..1 | OBReadDirectDebit1/Data/DirectDebit/DirectDebitId | A unique and immutable identifier used to identify the direct debit resource. This identifier has no meaning to the account owner. | Max40Text | ||
MandateIdentification | 1..1 | OBReadDirectDebit1/Data/DirectDebit/MandateIdentification | Direct Debit reference. For AUDDIS service users provide Core Reference. For non AUDDIS service users provide Core reference if possible or last used reference. | Max35Text | ||
DirectDebitStatusCode | 0..1 | OBReadDirectDebit1/Data/DirectDebit/DirectDebitStatusCode | Specifies the status of the direct debit in code form. | OBExternalDirectDebitStatus1Code | Active Inactive | |
Name | 1..1 | OBReadDirectDebit1/Data/DirectDebit/Name | Name of Service User. | Max70Text | ||
PreviousPaymentDateTime | 0..1 | OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentDateTime | Date of most recent direct debit collection. | ISODateTime | ||
PreviousPaymentAmount | 0..1 | OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmount | The amount of the most recent direct debit collection. | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..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} |
The OBReadProduct1 object will be used for the call to:
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.
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadProduct1 | OBReadProduct1 | OBReadProduct1 | ||||
Data | 1..1 | OBReadProduct1/Data | OBReadDataProduct1 | |||
Product | 0..n | OBReadProduct1/Data/Product | OBProduct1 | |||
AccountId | 1..1 | OBReadProduct1/Data/Product/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
ProductIdentifier | 1..1 | OBReadProduct1/Data/Product/ProductIdentifier | Identifier within the parent organisation for the product. Must be unique in the organisation. | xs:string | ||
ProductType | 1..1 | OBReadProduct1/Data/Product/ProductType | Descriptive code for the product category. | OBExternalProductType1Code | BCA PCA | |
ProductName | 0..1 | OBReadProduct1/Data/Product/ProductName | The name of the product used for marketing purposes from a customer perspective. I.e. what the customer would recognise. | xs:string | ||
SecondaryProductIdentifier | 0..1 | OBReadProduct1/Data/Product/SecondaryProductIdentifier | Identifier within the parent organisation for the product. Must be unique in the organisation. | xs:string |
The OBReadStandingOrder1 object will be used for the call to:
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.
Notes:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadStandingOrder1 | OBReadStandingOrder1 | OBReadStandingOrder1 | ||||
Data | 1..1 | OBReadStandingOrder1/Data | OBReadDataStandingOrder1 | |||
StandingOrder | 0..n | OBReadStandingOrder1/Data/StandingOrder | Account to or from which a cash entry is made. | OBStandingOrder1 | ||
AccountId | 1..1 | OBReadStandingOrder1/Data/StandingOrder/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
StandingOrderId | 0..1 | OBReadStandingOrder1/Data/StandingOrder/StandingOrderId | A unique and immutable identifier used to identify the standing order resource. This identifier has no meaning to the account owner. | Max40Text | ||
Frequency | 1..1 | OBReadStandingOrder1/Data/StandingOrder/Frequency | EvryWorkgDay - PSC070 IntrvlWkDay:PSC110:PSC080 (PSC070 code + PSC110 + PSC080) WkInMnthDay:PSC100:PSC080 (PSC070 code + PSC100 + PSC080) IntrvlMnthDay:PSC120:PSC090 (PSC070 code + PSC120 + PSC090) QtrDay: + either (ENGLISH, SCOTTISH or RECEIVED) PSC070 + PSC130 The following response codes may be generated by this data element: PSC070: T221 - Schedule code must be a valid enumeration value. PSC070: T245 - Must be provided for standing order only. PSC080: T222 - Day in week must be within defined bounds (range ì1î to ì5î). PSC080: T229 - Must be present if Schedule Code = ìIntrvlWkDayî. PSC080: T231 - Must be present if Schedule Code = ìWkInMnthDayî. PSC090: T223 - Day in month must be within defined bounds (range ì-5î to ì31î excluding: 0 & 00). PSC090: T233 - Must be present if Schedule Code = ìIntrvlMnthDayî. PSC100: T224 - Week in month must be within defined bounds (range ì1î to ì5î). PSC100: T232 - Must be present if Schedule Code = ìWkInMnthDayî. PSC110: T225 - Interval in weeks must be within defined bounds (range ì1î to ì9î). PSC110: T230 - Must be present if Schedule Code = ìIntrvlWkDayî. PSC120: T226 - Interval in months must be a valid enumeration value (range ì1î to ì6î, ì12î and ì24î). PSC120: T234 - Must be present if Schedule Code = ìIntrvlMnthDayî. PSC130: T227 - Quarter Day must be a valid enumeration value. PSC130: T235 - Must be present if Schedule Code = ìQtrDayî. The regular expression for this element combines five smaller versions for each permitted pattern. To aid legibility - the components are presented individually here: EvryWorkgDay IntrvlWkDay:0[1-9]:0[1-5] WkInMnthDay:0[1-5]:0[1-5] IntrvlMnthDay:(0[1-6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01]) QtrDay:(ENGLISH|SCOTTISH|RECEIVED) Mandatory/Conditional/Optional/Parent/Leaf: OL Type: 35 char string Regular Expression(s): (EvryWorkgDay)|(IntrvlWkDay:0[1-9]:0[1-5])|(WkInMnthDay:0[1-5]:0[1-5])|(IntrvlMnthDay:(0[1- 6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01]))|(QtrDay:(ENGLISH|SCOTTISH|RECEIVED)) | Max35Text | ||
Reference | 0..1 | OBReadStandingOrder1/Data/StandingOrder/Reference | Unique 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 | ||
FirstPaymentDateTime | 0..1 | OBReadStandingOrder1/Data/StandingOrder/ FirstPaymentDateTime | The date on which the first payment for a Standing Order schedule will be made. | ISODateTime | ||
FirstPaymentAmount | 0..1 | OBReadStandingOrder1/Data/StandingOrder/ FirstPaymentAmount | The amount of the first Standing Order | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..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} | |
NextPaymentDateTime | 1..1 | OBReadStandingOrder1/Data/StandingOrder/ NextPaymentDateTime | The date on which the next payment for a Standing Order schedule will be made. | ISODateTime | ||
NextPaymentAmount | 1..1 | OBReadStandingOrder1/Data/StandingOrder/ NextPaymentAmount | The amount of the next Standing Order | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..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} | |
FinalPaymentDateTime | 0..1 | OBReadStandingOrder1/Data/StandingOrder/ FinalPaymentDateTime | The date on which the final payment for a Standing Order schedule will be made. | ISODateTime | ||
FinalPaymentAmount | 0..1 | OBReadStandingOrder1/Data/StandingOrder/ FinalPaymentAmount | The amount of the final Standing Order | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..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} | |
Servicer | 0..1 | OBReadStandingOrder1/Data/StandingOrder/Servicer | Party 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 | ||
SchemeName | 1..1 | OBReadStandingOrder1/Data/StandingOrder/ Servicer/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalFinancialInstitutionIdentification2Code | BICFI UKSortCode | |
Identification | 1..1 | OBReadStandingOrder1/Data/StandingOrder/ Servicer/Identification | Unique and unambiguous identification of the servicing institution. | Max35Text | ||
CreditorAccount | 0..1 | OBReadStandingOrder1/Data/StandingOrder/ CreditorAccount | Provides the details to identify the beneficiary account. | OBCashAccount1 | ||
SchemeName | 1..1 | OBReadStandingOrder1/Data/StandingOrder/ CreditorAccount/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | OBExternalAccountIdentification2Code | BBAN IBAN | |
Identification | 1..1 | OBReadStandingOrder1/Data/StandingOrder /CreditorAccount/Identification | Beneficiary account identification. | Max34Text | ||
Name | 0..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 | ||
SecondaryIdentification | 0..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 |
The OBReadTransaction1 object will be used for the call to:
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.
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)
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.
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadTransaction1 | OBReadTransaction1 | OBReadTransaction1 | ||||
Data | 1..1 | OBReadTransaction1/Data | OBReadDataTransaction1 | |||
Transaction | 0..n | OBReadTransaction1/Data/Transaction | Provides further details on an entry in the report. | OBTransaction1 | ||
AccountId | 1..1 | OBReadTransaction1/Data/Transaction/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
TransactionId | 0..1 | OBReadTransaction1/Data/Transaction/TransactionId | Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable. | Max40Text | ||
TransactionReference | 0..1 | OBReadTransaction1/Data/Transaction/TransactionReference | Unique reference for the transaction. This reference is optionally populated, and may as an example be the FPID in the Faster Payments context. | Max35Text | ||
Amount | 1..1 | OBReadTransaction1/Data/Transaction/Amount | Amount of money in the cash transaction entry. | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..1 | OBReadTransaction1/Data/Transaction/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} | |
CreditDebitIndicator | 1..1 | OBReadTransaction1/Data/Transaction/CreditDebitIndicator | Indicates whether the transaction is a credit or a debit entry. | OBCreditDebitCode | Credit Debit | |
Status | 1..1 | OBReadTransaction1/Data/Transaction/Status | Status of a transaction entry on the books of the account servicer. | OBEntryStatus1Code | Booked Pending | |
BookingDateTime | 1..1 | OBReadTransaction1/Data/Transaction/BookingDateTime | Date 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 | ||
ValueDateTime | 0..1 | OBReadTransaction1/Data/Transaction/ValueDateTime | Date 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 | ||
TransactionInformation | 0..1 | OBReadTransaction1/Data/Transaction/TransactionInformation | Further details of the transaction. This is the transaction narrative, which is unstructured text. | Max500Text | ||
AddressLine | 0..1 | OBReadTransaction1/Data/Transaction/AddressLine | Information that locates and identifies a specific address for a transaction entry, that is presented in free format text. | Max70Text | ||
BankTransactionCode | 0..1 | OBReadTransaction1/Data/Transaction/ BankTransactionCode | Set of elements used to fully identify the type of underlying transaction resulting in an entry. | OBBankTransactionCodeStructure1 | ||
Code | 1..1 | OBReadTransaction1/Data/Transaction/ BankTransactionCode/Code | Specifies the family within a domain. | ExternalBankTransactionFamily1Code | ||
SubCode | 1..1 | OBReadTransaction1/Data/Transaction/ BankTransactionCode/SubCode | Specifies the sub-product family within a specific family. | ExternalBankTransactionSubFamily1Code | ||
ProprietaryBankTransactionCode | 0..1 | OBReadTransaction1/Data/Transaction/ ProprietaryBankTransactionCode | Set of elements to fully identify a proprietary bank transaction code. | ProprietaryBankTransactionCodeStructure1 | ||
Code | 1..1 | OBReadTransaction1/Data/Transaction/ ProprietaryBankTransactionCode/Code | Proprietary bank transaction code to identify the underlying transaction. | Max35Text | ||
Issuer | 0..1 | OBReadTransaction1/Data/Transaction/ ProprietaryBankTransactionCode/Issuer | Identification of the issuer of the proprietary bank transaction code. | Max35Text | ||
Balance | 0..1 | OBReadTransaction1/Data/Transaction/Balance | Set 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 | ||
Amount | 1..1 | OBReadTransaction1/Data/Transaction/Balance/Amount | Amount of money of the cash balance after a transaction entry is applied to the account.. | ActiveOrHistoricCurrencyAndAmount | TotalDigits: 18 FractionDigits: 5 | |
Currency | 1..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} | |
CreditDebitIndicator | 1..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. | OBCreditDebitCode | Credit Debit | |
Type | 1..1 | OBReadTransaction1/Data/Transaction/ Balance/Type | Balance type, in a coded form. | OBBalanceType1Code | ClosingAvailable ClosingBooked Expected ForwardAvailable Information InterimAvailable InterimBooked OpeningAvailable OpeningBooked PreviouslyClosedBooked | |
MerchantDetails | 0..1 | OBReadTransaction1/Data/Transaction/ MerchantDetails | Details of the merchant involved in the transaction. | OBMerchantDetails1 | ||
MerchantName | 0..1 | OBReadTransaction1/Data/Transaction/ MerchantDetails/MerchantName | Name by which the merchant is known. | Max350Text | ||
MerchantCategoryCode | 0..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 |
This section gives the definitions for enumerations used in the Account Info APIs.
Code Class | Name | Definition |
---|---|---|
OBBalanceType1Code | ClosingAvailable | Closing balance of amount of money that is at the disposal of the account owner on the date specified. |
OBBalanceType1Code | ClosingBooked | Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. |
OBBalanceType1Code | Expected | Balance, composed of booked entries and pending items known at the time of calculation , which projects the end of day balance if everything is booked on the account and no other entry is posted. |
OBBalanceType1Code | ForwardAvailable | Forward available balance of money that is at the disposal of the account owner on the date specified. |
OBBalanceType1Code | Information | Balance for informational purposes. |
OBBalanceType1Code | InterimAvailable | Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
OBBalanceType1Code | InterimBooked | Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
OBBalanceType1Code | OpeningAvailable | Opening balance of amount of money that is at the disposal of the account owner on the date specified. |
OBBalanceType1Code | OpeningBooked | Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. |
OBBalanceType1Code | PreviouslyClosedBooked | Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. |
OBCreditDebitCode | Credit | Operation is a credit |
OBCreditDebitCode | Debit | Operation is a debit |
OBEntryStatus1Code | Booked | Booked means that the transfer of money has been completed between account servicer and account owner Usage : Status Booked does not necessarily imply finality of money as this depends on other factors such as the payment system used, the completion of the end- to-end transaction and the terms agreed between account servicer and owner. Status Booked is the only status that can be reversed. |
OBEntryStatus1Code | Pending | Booking on the account owner's account in the account servicer's ledger has not been completed. Usage : this can be used for expected items, or for items for which some conditions still need to be fulfilled before they can be booked. If booking takes place, the entry will be included with status Booked in subsequent account report or statement. Status Pending cannot be reversed. |
OBExternalAccountIdentification2Code | BBAN | Basic Bank Account Number (BBAN) - identifier used nationally by financial institutions, ie, in individual countries, generally as part of a National Account Numbering Scheme(s), to uniquely identify the account of a customer. |
OBExternalAccountIdentification2Code | IBAN | An 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)". |
OBExternalDirectDebitStatus1Code | Active | The direct debit mandate is active. |
OBExternalDirectDebitStatus1Code | Inactive | The direct debit mandate is inactive. |
OBExternalFinancialInstitutionIdentification2Code | BICFI | Valid 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. |
OBExternalFinancialInstitutionIdentification2Code | UKSortCode | United Kingdom (UK) Sort Code - identifies British financial institutions on the British national clearing systems. The sort code is assigned by Payments UK. |
OBExternalLimitType1Code | Pre-Agreed | The amount of an arranged lending limit that has been agreed with the account holder |
OBExternalLimitType1Code | Temporary | The amount of a temporary lending limit that has been agreed with the account holder |
OBExternalLimitType1Code | Emergency | The amount of an arranged lending limit that can be borrowed on top of pre-agreed lending, that has been agreed with the account holder. |
OBExternalPermissions1Code | ReadAccountsBasic | Permission to read basic account information. |
OBExternalPermissions1Code | ReadAccountsDetail | Access to additional elements in the account payload. |
OBExternalPermissions1Code | ReadBalances | Permission to read all balance information. |
OBExternalPermissions1Code | ReadBeneficiariesBasic | Permission to read basic beneficiary details. |
OBExternalPermissions1Code | ReadBeneficiariesDetail | Access to additional elements in the beneficiaries payload. |
OBExternalPermissions1Code | ReadDirectDebits | Permission to read all direct debit information. |
OBExternalPermissions1Code | ReadStandingOrdersBasic | Permission to read standing order information. |
OBExternalPermissions1Code | ReadStandingOrdersDetail | Access to additional elements in the standing-orders payload. |
OBExternalPermissions1Code | ReadTransactionsBasic | Permission to read basic transaction information. |
OBExternalPermissions1Code | ReadTransactionsDetail | Access to additional elements in the transactions payload. |
OBExternalPermissions1Code | ReadTransactionsCredits | Access to only credit transactions. |
OBExternalPermissions1Code | ReadTransactionsDebits | Access to only debit transactions. |
OBExternalPermissions1Code | ReadProducts | Permission to read all product information. |
OBExternalProductType1Code | BCA | Business Current Account |
OBExternalProductType1Code | PCA | Personal Current Account |
OBExternalRequestStatus1Code | Authorised | The account request has been successfully authorised. |
OBExternalRequestStatus1Code | AwaitingAuthorisation | The account request is awaiting further authorisation. |
OBExternalRequestStatus1Code | Rejected | The account request has been rejected. |
OBExternalRequestStatus1Code | Revoked | The account request has been revoked via the ASPSP interface. |
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:
No additional Sequence Diagrams are given for the Usage Examples - as they do not differ from the Sequence Diagram in the Overview.
This set of payload examples is for an AISP:
In this scenario:
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: 2017-06-13T11:36:09 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": {} } |
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": "AwaitingAuthentication", "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": { "total-pages": 1 } } |
This is an example of a GET request which is made before the account request resource is authorised.
GET /account-requests/88379 HTTP/1.1 Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
This is an example of a GET request which is made after the account request resource is authorised.
GET /account-requests/88379 HTTP/1.1 Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
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.
GET /accounts HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": "BBAN", "Identification": "10203345", "Name": "Mr Kevin", "SecondaryIdentification": "00021" }, "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" } }, { "AccountId": "31820", "Currency": "GBP", "Nickname": "Household", "Account": { "SchemeName": "BBAN", "Identification": "10203348", "Name": "Mr Kevin" }, "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" } } ] }, "Links": { "self": "/accounts/" }, "Meta": { "total-pages": 1 } } |
An AISP can also retrieve the account resource details specifically for AccountId 22289
GET /accounts/22289 HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": "BBAN", "Identification": "10203345", "Name": "Mr Kevin", "SecondaryIdentification": "00021" }, "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" } } ] }, "Links": { "self": "/accounts/22289" }, "Meta": { "total-pages": 1 } } |
GET /accounts/22289/balances HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
GET /balances HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
GET /accounts/22289/beneficiaries HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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", "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" }, "CreditorAccount": { "SchemeName": "BBAN", "Identification": "12345678", "Name": "Mrs Juniper" } } ] }, "Links": { "self": "/accounts/22289/beneficiaries/" }, "Meta": { "total-pages": 1 } } |
GET /beneficiaries HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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", "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" }, "CreditorAccount": { "SchemeName": "BBAN", "Identification": "12345678", "Name": "Mrs Juniper" } }, { "AccountId": "31820", "BeneficiaryId": "Ben37", "Reference": "Golf Club", "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC875622" }, "CreditorAccount": { "SchemeName": "BBAN", "Identification": "98675421", "Name": "Mr Large" } } ] }, "Links": { "self": "/beneficiaries/" }, "Meta": { "total-pages": 1 } } |
GET /accounts/22289/direct-debits HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
GET /direct-debits HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
GET /accounts/22289/product HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": "CC", "ProductType": "Current Account", "ProductName": "321" } ] }, "Links": { "self": "/accounts/22289/product" }, "Meta": { "total-pages": 1 } } |
GET /products HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": "CC", "ProductType": "Current Account", "ProductName": "321" }, { "AccountId": "31820", "ProductIdentifier": "CC", "ProductType": "Current Account", "ProductName": "321" } ] }, "Links": { "self": "/products/" }, "Meta": { "total-pages": 1 } } |
GET /accounts/22289/standing-orders HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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" }, "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" }, "CreditorAccount": { "SchemeName": "BBAN", "Identification": "12345678", "Name": "Mrs Juniper" } } ] }, "Links": { "self": "/accounts/22289/standing-orders/" }, "Meta": { "total-pages": 1 } } |
GET /standing-orders HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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" }, "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC802001" }, "CreditorAccount": { "SchemeName": "BBAN", "Identification": "12345678", "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" }, "Servicer": { "SchemeName": "UKSortCode", "Identification": "SC236054" }, "CreditorAccount": { "SchemeName": "BBAN", "Identification": "90179017", "Name": "Mr Tee" } } ] }, "Links": { "self": "/standing-orders/" }, "Meta": { "total-pages": 1 } } |
GET /accounts/22289/transactions HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
None of the transactions included in the payload are Ecommerce transactions - so MerchantDetails are not included in the examples.
GET /transactions HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": "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" } }, { "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": { "total-pages": 1 } } |
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.
DELETE /account-requests/88379 HTTP/1.1 Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d |
HTTP/1.1 204 No Content x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d |
This set of payload examples is for an AISP:
In this scenario:
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: 2017-06-13T11:36:09 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": {} } |
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": "AwaitingAuthentication", "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": { "total-pages": 1 } } |
GET /accounts HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
GET /accounts/22289/balances HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 1 } } |
In this example - the AISP does not have access to call the transactions endpoint. This will result in a 403 error.
GET /accounts/22289/transactions HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
HTTP/1.1 403 Forbidden x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d |
The example below illustrates how an ASPSP may return a paginated response.
GET /accounts/22289/transactions HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 20 } } |
The AISP can follow the links provided in the Links section of the payload to navigate to the first, last, next and previous pages:
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: 2017-06-13T11:36:09 x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
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": { "total-pages": 20 } } |
This flow assumes that the following Steps have been completed successfully:
The AISP attempts to provide an expired or missing access token to the ASPSP in an attempt to Request Data
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 |
This flow assumes that the following Steps have been completed successfully:
The AISP provides a malformed request to the ASPSP in an attempt to setup an Account Request.
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 |
This flow assumes that the following Steps have been completed successfully:
The AISP provides a (valid) access token which does not have a valid scope (or link to the correct Permissions) to Request Data
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 |
This flow assumes that the following Steps have been completed successfully:
The AISP provides a (valid) access token which is used to generate a burst of multiple requests to retrieve an Accounts resource.
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} ASPSP Resource Server -> AISP: HTTP 429 (Too Many Requests) end end |
This flow assumes that the following Steps have been completed successfully:
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.
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 |