Version | Date | Author | Comments |
---|---|---|---|
2.0-rc1 | Open Banking Read/Write API Team | This is the initial draft version for rc1 | |
2.0-rc2 | Open Banking Read/Write API Team | Moved Usage Examples from Account and Transactions Specification to this page Updated the Response Headers section to state the x-fapi-interaction-id should be generated if required. Matches FAPI specification. Clarified that x-fapi-financial-id corresponds to the organization id of the ASPSP in the Open Banking Directory. Clarified that x-jws-signature is only valid for some APIs. Removed x-jws-signature from examples. Changes to the Message Signing section to:
Added error code 415 Unsupported Media Type, for invalid Content-Type header value | |
2.0-rc3 | Open Banking Read/Write API Team | This is the initial draft version for rc3. Updates:
Errata:
| |
2.0.0 | Open Banking Read/Write API Team | This is the baseline version. No changes from v2.0-rc3, other than addition of release note. |
This release note explains what's new in Read/Write Data API Specifications v2.0.0.
For clarity, the specifications have now been divided as follows:
Specification | Changes in this release |
---|---|
Read/Write Data API Specification Provides a description of the elements that are common across all the Read/Write Data APIs. (This should be read in conjunction with the latest individual Account & Transaction and Payment Initiation API Specifications as below). | Minor clarifications and amendments (see Version Control above). |
Account and Transaction API Specification Describes the flows and payloads for the ‘Read’ Data APIs. (This should be read in conjunction with the Read/Write Data API Specification as above). | Changes have been made to the Account and Transaction API Specification to support Open Data and to extend the API to cover other PSD2 in-scope payment accounts. Changes as summarised below. |
Payment Initiation API Specification Describes the flows and payloads for the ‘Write’ Data APIs. (This should be read in conjunction with the Read/Write Data API Specification as above). | No changes have been made to the Payment Initiation API in this release. ASPSPs and TPPs should refer to v1.1.0. of the Payment Initiation API Specification. |
Supporting Open Data for standardised back-book products (Personal Current Accounts ‘PCA’ and Business Current Accounts ‘BCA’)
For PCA and BCA accounts, v1 of the read/write API specifications included a 'products' endpoint within the Account Information and Transaction API. This enabled a referential model, where a TPP could access the PSU's account and retrieve the product ID for on-sale accounts. This ID could then be used to reference the corresponding product information in the Open Data standard. Version 2 extends the capability of the ‘products’ endpoint within the Account Information and Transaction API so TPP’s can directly access key product data for PSU’s who have a back book product, in the event the back-book product is not available in the Open Data standard.
High level changes from v1.1 include:
Extension to PSD2 in-scope accounts (sterling)
Version 2.0.0 extends the Account and Transaction API to cover other PSD2 in-scope payment accounts (limited to GBP accounts) in addition to personal and business current accounts covered by v1. These additional payment accounts are as follows:
High level changes from v1.1 include:
As per the CMA’s Notice of approval of changes to the Agreed Timetable and Project Plan (Retail Banking Market Investigation Order 2017) published on 22 November 2017, the implementation of this standard by ASPSPs will be split as follows:
The Read/Write Data API Specification provides a description of the elements that are common across all the Read/Write Data APIs.
This specification should be read in conjunction with the individual Read/Write API Specifications for Payment Initiation, Account & Transaction Information & Confirmation of Funds.
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 begins with an introduction to how the APIs are used.
Security & Access Control: Specifies the means for TPPs and PSUs to authenticate themselves and provide consent.
Data Model: Describes the data model for the API payloads.
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 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:
It is intended that the API flows will be extended to cater for more complex use-cases in subsequent releases - and we have kept this in mind during the design.
Idempotency is difficult to implement consistently and leverage consistently.
As a result, idempotency is used sparingly in the Open Banking API specifications; with a preference to allow TPPs to simply re-submit a request under failure conditions.
APIs have been defined to be idempotent, where not doing so would cause a poor PSU user-experience or increase false positive risk indicators.
Digital signatures will facilitate non-repudiation for Open Banking APIs.
However, the solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / Message Signing.
The API will be designed so that it is agnostic to the underlying payment scheme that is responsible for carrying out the payment.
As a result, we will not design field lengths and payloads to only match the Faster Payments message, and will instead rely on the field lengths and definitions in ISO 20022. Due diligence has been carried out to ensure that the API has the necessary fields to function with Bacs payments - as per agreed scope.
We will provide further mapping guidance to ensure that differences are understood between the Open Banking Payment API standard, and FPS and Bacs schemes where applicable.
The API uses two status codes that serve two different purposes:
A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.
However, considering that some of the resources described in these specifications do not have a primary key in the system of record, the Id field will be optional for some resources.
An ASPSP that chooses to populate optional ID fields must ensure that the values are unique and immutable.
For endpoints and fields within each resource, the following definitions apply:
'Online Channel' refers to the superset of the ASPSPs website interface or mobile application (i.e. any information provided to the PSU in either channel).
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). References to a "TPP" in the specification relate to a piece of registered software with an ASPSP (with a specific client_id). |
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 |
Card Based Payment Instrument Issuer | CBPII | Legal Entity | TPP | A TPP that issues card based payment instruments to PSUs and requires access to the Confirmation of Funds API. |
The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - Section 8.1)
However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "Happy Birthday 🎂🎂!" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP must respond with an HTTP 400 (Bad Request) status code.
All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below:
2017-04-05T10:43:07+00:00 |
All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:
Sun, 10 Sep 2017 19:43:31 UTC |
All dates in the JWT claims are expressed as a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
//Sun, 12 Feb 2018 14:45:00 UTC 1518446700 |
The resources defined by these APIs may be addressed through a path structure consisting of the following parts:
Examples:
/superbank/open-banking/v2.0/payments
/open-banking/v2.0/account-requests
/apis/open-banking/v2.1/accounts
Header Value | Notes | POST Requests | GET Requests | DELETE Requests |
---|---|---|---|---|
x-fapi-financial-id | The unique id of the ASPSP to which the request is issued. The unique id will be issued by OB and corresponds to the Organization Id of the ASPSP in the Open Banking Directory. | 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. If set to any other value, ASPSP must respond with a 415 Unsupported Media Type. | Mandatory | Do not use | Do not use |
Accept | Standard HTTP Header; Determine the Content-Type that is required from the Server. If specified, it must have the value If set to an unacceptable value the ASPSP must respond with a 406 Not Acceptable. If not specified, default is application/json | Optional | Optional | Do not use |
x-idempotency-key | Custom HTTP Header; Unique request identifier to support idempotency. Mandatory for POST requests to idempotent resource end-points. Must not be specified for other requests. | Optional | Do not use | Do not use |
x-jws-signature | Header containing a detached JWS signature of the body of the payload. Refer to resource specific documentation on when this header must be specified. | API specific | API specific | API specific |
(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 for all endpoints, except the GET ../statements/{StatementId}/file endpoint, where it is up to the ASPSP to specify available options. | Mandatory |
x-jws-signature | Header containing a detached JWS signature of the body of the payload. Refer to resource specific documentation on when this header must be returned. | API specific |
x-fapi-interaction-id | An RFC4122 UID used as a correlation id. The ASPSP must set the response header | Mandatory |
Retry-After | Header indicating the time (in seconds) that the TPP should wait before retrying an operation. The ASPSP should include this header along with responses with the HTTP status code of 429 (Too many requests). | Optional |
The following are the HTTP response codes for the different HTTP methods - across all Read/Write 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 | |
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. Re-authenticating the PSU may result in an appropriate token that may be used. | Yes | Yes | Yes |
Token has incorrect scope or a security policy was violated. | 403 Forbidden | The operation was refused access. Re-authenticating the PSU is unlikely to remediate the situation. | Yes | Yes | Yes |
The TPP tried to access the resource with a method that is not supported. | 405 Method Not Allowed | Yes | Yes | Yes | |
The request contained an Accept header other than permitted media types and a character set other than UTF-8 | 406 Not Acceptable | Yes | Yes | Yes | |
The operation was refused because the payload is in a format not supported by this method on the target resource. | 415 Unsupported Media Type | Yes | No | No | |
The operation was refused as too many requests have been made within a certain timeframe. | 429 Too Many Requests | Throttling is a NFR. The ASPSP should include a Retry-After header in the response indicating how long the TPP must wait before retrying the operation. | 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 a 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 /payments/22289 where 22289 is not a valid PaymentId, 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 a payment with a PaymentId that does not exist | GET /payments/1001 | 400 (Bad Request) |
TPP attempts to retrieve a resource that is not defined | GET /bulk | 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 status API endpoint for payment-submissions | GET /payment-submissions/1002 | 404 (Not Found) |
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": "https://api.alphabank.com/open-banking/v1.0/accounts/1000/standing-orders/"
},
"Meta": {
"TotalPages": 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 the TPP uses an access token that is no longer valid, the situation could potentially be remedied by asking the PSU to re-authenticate. This should be indicated by a 401 (Unauthorized) status code.
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:
If idempotency is implemented for an API endpoint:
Overview
This section provides an overview of how message signing is implemented for the Open Banking Read/Write APIs.
The APIs require TLS 1.2 Mutual Authentication and this may 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 the signature may be verified.
Not all API requests and responses are signed. Whether message signing is mandatory, supported or not supported is documented along with each API.
The TPP must sign the HTTP body of each API request that requires message signing.
The ASPSP must sign the HTTP body of each API response that requires message signing.
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 sign the message with one of the following algorithms:
The signer must use a valid signing certificate issued by Open Banking to the signer.
It should be noted that:
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. |
typ | This is an optional claim. If it is specified, it must be set to the value "JOSE" |
cty | This is an optional claim. If it is specified, it must be set to the value "json" or "application/json". |
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 JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names) |
http://openbanking.org.uk/iss | This must be a string containing the id of the TPP. This must match the dn of the signing certificate. This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names) |
crit | This must be a string array consisting of the values "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss" This indicates that the JWS signature validator must understand and process the three additional claims. |
The signer must compute the signature as a detached JWS as defined in RFC 7515, Appendix F
"One way to do this is to create a JWS in the normal fashion using a representation of the content as the payload but then delete the payload representation from the JWS and send this modified object to the recipient rather than the JWS."
...Note that this method needs no support from JWS libraries, as applications can use this method by modifying the inputs and outputs of standard JWS libraries.
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.
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 validate that the typ header if specified has the value JOSE.
The verifier must validate that the cty header if specified it resolves to application/json.
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 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 verifier 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 as defined in RFC 7515, Appendix F.
To use the modified object, the recipient reconstructs the JWS by re-inserting the payload representation into the modified object and uses the resulting JWS in the usual manner. Note that this method needs no support from JWS libraries, as applications can use this method by modifying the inputs and outputs of standard JWS libraries.
{ "alg": "RS512", "kid": "90210ABAD", "b64": false, "http://openbanking.org.uk/iat": 1501497671, "http://openbanking.org.uk/iss": "C=UK, ST=England, L=London, O=Acme Ltd.", "crit": [ "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"] } |
An ASPSP must provide limited support of filtering on GET operations that return multiple records.
The filter parameters, are always specific to particular field(s) of the resource, and follow the rules/formats defined under the resource's data dictionary.
In case of DateTime type filter parameters, values must be specified in ISO8601 format. If the DateTime contains a timezone, the ASPSP must ignore the timezone component.
The filter values will be assumed to refer to the same timezone as the timezone in which the resource is maintained.
An ASPSP MAY provide a paginated response for GET operations that return multiple records.
In such a situation, the ASPSP MUST:
For a paginated responses, the ASPSP SHOULD ensure that the number of records on a page are within reasonable limits - a minimum of 25 records (except on the last page where there are no further records) and a maximum of 1000 records.
Additionally, the ASPSP MAY provide:
As with all other responses, the ASPSP MUST include a "self" link to the resource in the Links.Self field as described in the Links sections.
This standard does not specify how the pagination parameters are passed by the ASPSP and each ASPSP may employ their own mechanisms to paginate the response.
If the original request from the AISP included filter parameters, the paginated response must return only results that match the filter.
ASPSPs are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.
Archiving of resources will be for ASPSPs to defined based on their internal Legal and Regulatory requirements.
In addition:
ASPSPs must only delete expired intent-ids 24 hours after creation
To access each of the APIs, the API must be called with an access token in the HTTP Authorization
header.
The scopes required with these access tokens and the grant type used to get the access token are specified in the specific API documentation.
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 enforce payments of a specified amount on a specified date).
An intent is used to define the fine-grained permissions that are granted by the PSU to the TPP.
The act of providing authorisation of an intent by a PSU to an ASPSP is called consent authorisation.
The Open Banking Read/Write APIs use a variety of intents such payments and account-requests.
A TPP requests an ASPSP to create intent by using a client credentials grant. The ASPSP creates the intent and responds with the intent-id. The TPP then redirects the PSU to the ASPSP to authorise consent for the intent, passing in an intent-id as a parameter.
This is done through an authorization grant flow and results in the issuance of an access token tied to the authorised intent.
An access token is bound to a single PSU and an intent.
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 an error parameter indicating the error that occurred.
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 must get the PSU to initiate a fresh authorisation code grant.
An ASPSP may change the state of an authorized intent under certain situations to indicate that the intent is no longer authorized.
E.g., an account-request may be reset to a status of "AwaitingAuthorisation"
In such a situation, the PISP may request the intent to be re-authorized by initiating an authorization code grant with the intent-id of the offending intent specified in the request parameter.
An ASPSP may change the state of an authorized intent under certain situations to indicate that the intent is rejected. This is a terminal state and the TPP must not attempt to initiate an authorization code grant using the intent.
This section gives an overview of the top level structure for the API payloads for the Openbanking Read/Write APIs.
The data contained within the Data
section is documented with each individual API endpoint.
The top level request structure for Open Banking Read/Write APIs:
{ "Data": { ... }, "Risk": { ... } } |
The Data
section contains the request data for the specific API request.
The structure of this element differs for each API endpoint.
The Risk
section contains risk indicators for the specific API request as provided by the TPP.
The risk indicators contained in this element may be different for each API endpoint.
The top level response structure for Openbanking Read/Write APIs:
{ "Data": { ... }, "Risk": { ... }, "Links": { ... }, "Meta": { ... } } |
In line with the principle of RESTful APIs, the full resource must be replayed as part of the response.
Two additional top level sections are included in the response for:
Links
Meta
The Links section is mandatory and will always contain absolute URIs to related resources,
The "Self" member is mandatory.
For example:
"Links": { "Self": "https://api.alphabank.com/open-banking/v1.0/payments/58923" } |
Where an API provides a paginated response, the Links
element must also contain the members First
, Prev
, Next
and Last
.
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 may be empty. An optional member is "TotalPages" which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.
For example:
"Meta": { "TotalPages": 13 } |
The usage examples for the individual APIs are documented in their respective pages.
This section provides usage examples for some repeating patterns that are used by multiple resources.
The example below illustrates how an ASPSP may return a paginated response.
Request
GET /accounts/22289/transactions HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
Paginated Resource Response
HTTP/1.1 200 OK x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Content-Type: application/json { "Data": { ... }, "Links": { "Self": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions/", "Last": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions?pg=20", "First": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions/", "Next": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions?pg=2" }, "Meta": { "TotalPages": 20, "FirstAvailableDateTime": "2017-05-03T00:00:00+00:00", "LastAvailableDateTime": "2017-12-03T00:00:00+00:00" } } |
The TPP may follow the links provided in the Links section of the payload to navigate to the first, last, next and previous pages:
Request Next Page of Results
GET /accounts/22289/transactions?pg=2 HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json |
Paginated Resource Response
HTTP/1.1 200 OK x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Content-Type: application/json { "Data": { ... }, "Links": { "Self": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions?pg=2", "Last": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions?pg=20", "First": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions/", "Next": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions?pg=3", "Prev": "https://api.alphabank.com/open-banking/v1.0/accounts/22289/transactions?pg=1" }, "Meta": { "TotalPages": 20, "FirstAvailableDateTime": "2017-05-03T00:00:00+00:00", "LastAvailableDateTime": "2017-12-03T00:00:00+00:00" } } |
This section provides some examples of error scenarios and the expected outputs.
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.
The ASPSP may optionally choose to return a 429 Response
participant PSU participant AISP participant ASPSP Authorisation Server participant ASPSP Resource Server alt AISP attempts to retrieve an Account Resource AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA loop Burst of multiple GET requests AISP -> ASPSP Resource Server: GET /accounts/{AccountId} opt ASPSP Resource Server -> AISP: HTTP 429 (Too Many Requests) end end end |
This flow assumes that the following Steps have been completed successfully:
The Step 3: Authorise 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 |