Versions Compared

Version Old Version 2 New Version 3
Changes made by

Girish (Unlicensed)

Girish (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleWhat are the Date Formats used in the API?

All date-time fields in responses must include the timezone. For Example:

2020-04-05T10:43:07+03:00

2020-05-03T14:43:41Z

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

All dates in the query string are represented in ISO-8601 date-time format and must not include the timezone. For example:

2020-04-05T10:43:07

2020-04-05

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

Tue, 10 Mar 2020 19:43:31 GMT+03:00

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 GMT until the date/time.

//Wed, 12 Feb 2020 14:45:00 GMT+03:00

1581507900

Expand
titleWhat will be the structure of resource URI path?

The path of the URI must follow the structure below

  • [participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[resource-id]/[sub-resource]

This consists of the following elements:

  • [participant-path-prefix]
    An optional ASPSP specific path prefix.

  • open-banking
    The constant string "open-banking".

  • [version]
    The version of the APIs expressed as /v[major-version].[minor-version]/.

  • [resource-group]
    The resource-group identifies the group of endpoints, to access the API (as "aisp", "pisp").

  • [resource]/[resource-id]
    Details the resource.

  • [sub-resource]
    Details the sub-resource.

An ASPSP must use the same participant-path-prefix and host name for all its resources.

Examples:

  • https://xyz.com/apis/open-banking/v1.1/pisp/domestic-payments

  • https://xyz.com/apis/open-banking/v1.1/aisp/account-access-consents

  • https://xyz.com/apis/open-banking/v3.1/aisp/accounts

  • https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234

  • https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234/transactions

Expand
titleWhat are Request Headers?

Header Value

Notes

POST Requests

GET Requests

DELETE Requests

PUT

Requests

PATCH
Requests

x-fapi-auth-date

The time when the User/Customer last logged in with the AISP/PISP. e.g., x-fapi-auth-date: Mon, 11 May 2020 19:43:31 GMT+03:00

Optional

Optional

Optional

Do not use

Optional

x-fapi-customer-ip-address

The User’s/Customer’s IP address if the User/Customer is currently logged in with the AISP/PISP.

Optional

Optional

Optional

Do not use

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

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

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, except for the endpoints that support Content-Type other than application/json (e.g POST /file-payment-consents/{ConsentId}/file), the ASPSP must specify the available options on their developer portals.
This must be set to application/jose+jwe for encrypted requests.
The AISP/PISP may provide additional information (e.g. a 'q' value and charset).

Mandatory

Do not use

Do not use

Mandatory

Mandatory

Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.
If the AISP/PISP expects an unencrypted response, it must indicate that the only a JSON response is accepted (e.g by setting the value to application/json) as a content header for all endpoints that respond with JSON.
If the AISP/PISP expects an encrypted response, it must indicate that the only a JWT response is accepted (e.g by setting the value to application/jose+jwe) as a content header for all endpoints that respond with JSON.
For endpoints that do not respond with JSON (e.g GET ../statements/{StatementId}/file), the ASPSP must specify the available options on their developer portals.
If set to an unacceptable value the ASPSP must respond with a 406 (Not Acceptable).
If not specified, the default is application/json.

Optional

Optional

Do not use

Optional

Optional

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

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

Mandatory

API specific

x-customer-user-agent

The header indicates the user-agent that the User/Customer is using.
The AISP/PISP may populate this field with the user-agent indicated by the User/Customer.
If the User/Customer is using a AISP/PISP mobile app, the AISP/PISP must ensure that the user-agent string is different from browser based user-agent strings.

Optional

Optional

Optional

Optional

Optional

Expand
titleWhat are Response Headers?

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 unencrypted endpoints, except the GET ../statements/{StatementId}/file and ../file-payment-consents/{ConsentId}/file endpoints, where it is up to the ASPSP to specify available options.
The ASPSP must return Content-type: application/jwe for all encrypted end-points

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. Where a signed response is indicated in the documentation this header should be returned for error responses where a response body is returned.

API specific

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.
The ASPSP must set the response header x-fapi-interaction-id to the value received from the corresponding fapi client request header or to a RFC4122 UUID value if the request header was not provided to track the interaction. The header must be returned for both successful and error responses.

Mandatory

Retry-After

Header indicating the time (in seconds) that the AISP/PISP 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

Expand
titleList of HTTP Status Codes

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

Returned by PUT 

Returned by PATCH 

Request completed successfully

200 OK

PUT will be specified to return the updated resource. A 200 status code is therefore appropriate.

No

Yes

No

Yes

Yes

Normal execution. The request has succeeded.

201 Created

The operation results in the creation of a new resource.

Yes

No

No

No

No

Delete operation completed successfully

204 No Content

 

No

No

Yes

No

No

Request has malformed, missing or non-compliant JSON body, URL parameters or header fields.

400 Bad Request

The requested operation will not be carried out.

Yes

Yes

Yes

Yes

     Yes

Authorization header missing or invalid token

401 Unauthorized

The operation was refused access.
Re-authenticating the User/Customer may result in an appropriate token that may be used.

Yes

Yes

Yes

Yes

Yes

Token has incorrect scope or a security policy was violated.

403 Forbidden

The operation was refused access.
Re-authenticating the User/Customer may result in an appropriate token that may be used

Yes

Yes

Yes

Yes

Yes

The AISP/PISP tried to access the resource with a method that is not defined

404Not found

 

Yes

Yes

Yes

Yes

Yes

The AISP/PISP tried to access the resource with a method that is not supported.

405 Method Not Allowed

 

Yes

Yes

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

Yes

Yes

The operation was refused as too many requests have been made within a certain timeframe.

429 Too Many Requests

ASPSPs may throttle requests when they are made in excess of their fair usage policy.
ASPSPs must document their fair usage policies in their developer portals.
The ASPSP must respond with this status if it throttles the request.
The ASPSP should include a Retry-After header in the response indicating how long the AISP/PISP must wait before retrying the operation.

Yes

Yes

No

Yes

Yes

Something went wrong on the API gateway or micro-service

500 Internal Server Error

The operation failed.

Yes

Yes

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.

ASPSPs must respond with error response in the OAuth/OIDC flow with mandatory alignment of the error codes to those specified in OpenID Connect Core Specification Section 3.1.2.6.

ASPSPs must respond with Open Banking Error Response Structure for all errors during API Calls.

Expand
titleDoes GET operation supports filtering?

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 may 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.

Expand
titleDoes GET operations supports pagination?

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

In such a situation, the ASPSP MUST:

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

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

For a paginated responses, the ASPSP may ensure that the number of records on a page are within reasonable limits, the minimum and maximum level for number of records may be decided based on agreement between ASPSP and AISP/PISP.

Additionally, the ASPSP MAY provide:

  • A link to the first page of results in the Links.First field.

  • A link to the last page of results in the Links.Last field.

  • The total number of pages in the Meta.TotalPages field.

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

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

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

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

Expand
titleWhat are the Archiving policies?

Archiving of resources will be for ASPSPs to define based on their internal Legal and Regulatory requirements.

Expand
titleWhat is Supplementary Data?

A number of resources in the specification include a section for Supplementary Data. This is intended to allow ASPSPs to accept or provide information in a request or response that is not catered for by other sections of the resource definition.

The Supplementary Data section is defined as an empty JSON object in the specification.

Wherever used, an ASPSP must define and document (on their developer portal) their own structure, usage and (mandatory/optional) requirements for Supplementary Data.

An ASPSP must not use Supplementary Data if an element already exists in the OBF standard that fulfils the requirement.

Expand
titleWhat will be the error flow if the access token is missing or expierd?

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

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent

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

Image Added

Expand
titleWhat will be the error flow if request payload is incomplete or malformed?

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

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent

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

Image Added

Expand
titleWhat will be the error flow if access token scope is missing or invalid?

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

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent

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

Image Added

Expand
titleWhat is the error flow if there is sudden burst of API requests?

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

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent

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

The ASPSP may optionally choose to return a 429 Response.

Image Added

Expand
titleWhat is the error flow if consent authorisation is failed?

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

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent Flow fails to succeed due to the USER/CUSTOMER providing invalid credentials to the ASPSP, resulting in no Authorization Code being generated.

Image Added