Version Control

Version

Date

Author

Comments

2.0-rc2

07 Feb 2018

Open Banking Read/Write API Team

This is the initial version following specification restructuring.

Modified usage examples:
- Removed references to x-jws-signature
- Updated link URLs
- Name-spaced AccountRequestIds in usage examples - as IntentIds are name-spaced in other usage examples. ASPSPs may construct the Intent-Id as they wish.
Updated Query endpoint input date guideline and filter example, to align with Decision 114

2.0-rc3

16 Feb 2018

Open Banking Read/Write API Team

This is the initial version for release candidate 3.

Updates:

Included StatusUpdateDateTime in the usage examples for the response payload.
Replaced ':' character with '-' in the name-spaced intent IDs in usage examples
Removed the Query endpoint.

2.0.0

27 Feb 2018

Open Banking Read/Write API Team

This is the baseline version. No changes from v2.0-rc3.

Endpoints

	Resource	HTTP Operation	Endpoint	Mandatory?	Scope	Grant Type	Idempotent	Request Object	Response Object
1	account-requests	POST	POST /account-requests	Mandatory	accounts	Client Credentials	No	OBReadRequest1	OBReadResponse1
2	account-requests	GET	GET /account-requests/{AccountRequestId}	Mandatory	accounts	Client Credentials			OBReadResponse1
3	account-requests	DELETE	DELETE /account-requests/{AccountRequestId}	Mandatory	accounts	Client Credentials	NA

POST /account-requests

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

This API effectively allows the AISP to send a copy of the consent to the ASPSP to authorise access to account and transaction information.
An AISP is not able to pre-select a set of accounts for account-request authorisation. This is because the behaviour of the pre-selected accounts, after authorisation, is not clear from a Legal perspective.
An ASPSP creates the account-request resource and responds with a unique AccountRequestId to refer to the resource.
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

Account Request Status

The PSU must authenticate with the ASPSP and authorise the account-request for the account-request to be successfully setup.

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.

After authorisation has taken place the account-request resource may have these following statuses.

	Status	Status Description
1	Rejected	The account request has been rejected.
2	Authorised	The account request has been successfully authorised.
3	Revoked	The account request has been revoked via the ASPSP interface.

Status Flow

This is the state diagram for the Status.

GET /account-requests/{AccountRequestId}

An AISP may optionally retrieve an 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.

The usage of this API endpoint will be subject to an ASPSP's fair usage policies.

Account Request Status

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

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

	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 must delete the account-request resource with the ASPSP before confirming consent revocation with the PSU.

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

Data Model

Account Requests - Request

The OBReadRequest1 object will be used for the call to:

POST /account-requests

UML Diagram

Notes:

The fields in the OBReadRequest1 object are described in the Consent Elements section
No fields have been identified for the Risk section

Data Dictionary

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 ReadOffers ReadPAN ReadParty ReadPartyPSU ReadProducts ReadScheduledPaymentsBasic ReadScheduledPaymentsDetail ReadStandingOrdersBasic ReadStandingOrdersDetail ReadStatementsBasic ReadStatementsDetail 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

Account Requests - Response

The OBReadResponse1 object will be used for the call to:

GET /account-requests/{AccountRequestId}

And response to:

POST /account-requests

UML Diagram

Notes:

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

Data Dictionary

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
CreationDateTime	1..1	OBReadResponse1/Data/CreationDateTime	Date and time at which the resource was created.	ISODateTime
Status	1..1	OBReadResponse1/Data/Status	Specifies the status of the account request resource.	OBExternalRequestStatus1Code	Authorised AwaitingAuthorisation Rejected Revoked
StatusUpdateDateTime	1..1	OBReadResponse1/Data/StatusUpdateDateTime	Date and time at which the resource status was updated.	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 ReadOffers ReadPAN ReadParty ReadPartyPSU ReadProducts ReadScheduledPaymentsBasic ReadScheduledPaymentsDetail ReadStandingOrdersBasic ReadStandingOrdersDetail ReadStatementsBasic ReadStatementsDetail 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

Usage Examples

Setup Account Request - All Permissions Granted

Request

Post Account Requests Request

POST /account-requests HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

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

Response

Post Account Requests Response

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "urn-alphabank-intent-88379",
    "Status": "AwaitingAuthorisation",,
    "StatusUpdateDateTime": "2017-05-02T00:00:00+00:00"
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail",
      "ReadOffers",
      "ReadPAN",
      "ReadParty",
      "ReadPartyPSU",
      "ReadScheduledPaymentsDetail",
      "ReadStatementsDetail"
    ],
    "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": "https://api.alphabank.com/open-banking/v2.0/account-requests/urn-alphabank-intent-88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Status - AwaitingAuthorisation

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

Request

Get Account Requests Request

GET /account-requests/urn-alphabank-intent-88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

Get Account Requests Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "urn-alphabank-intent-88379",
    "Status": "AwaitingAuthorisation",
    "StatusUpdateDateTime": "2017-05-02T00:00:00+00:00",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail",
      "ReadOffers",
      "ReadPAN",
      "ReadParty",
      "ReadPartyPSU",
      "ReadScheduledPaymentsDetail",
      "ReadStatementsDetail"
    ],
    "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": "https://api.alphabank.com/open-banking/v2.0/account-requests/urn-alphabank-intent-88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Status - Authorised

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

Request

Get Account Requests Request

GET /account-requests/urn-alphabank-intent-88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

Get Account Requests Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "urn-alphabank-intent-88379",
    "Status": "Authorised",
    "StatusUpdateDateTime": "2017-05-02T00:05:00+00:00",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesDetail",
      "ReadDirectDebits",
      "ReadProducts",
      "ReadStandingOrdersDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail",
      "ReadOffers",
      "ReadPAN",
      "ReadParty",
      "ReadPartyPSU",
      "ReadScheduledPaymentsDetail",
      "ReadStatementsDetail"
    ],
    "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": "https://api.alphabank.com/open-banking/v2.0/account-requests/urn-alphabank-intent-88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Delete Account Request

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

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

Request

Delete Account Requests Request

DELETE /account-requests/urn-alphabank-intent-88379 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d

Response

Delete Account Requests Response

HTTP/1.1 204 No Content
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d

Setup Account Request with Limited Permissions

Request

Post Account Requests Request

POST /account-requests HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

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

Response

Post Account Requests Response

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "AccountRequestId": "urn-alphabank-intent-88379",
    "Status": "AwaitingAuthorisation",
    "StatusUpdateDateTime": "2017-05-02T00:00:00+00:00",
    "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": "https://api.alphabank.com/open-banking/v2.0/account-requests/urn-alphabank-intent-88379"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Developer Zone

Account Requests v2.0.0

Version Control

Endpoints

POST /account-requests

Account Request Status

Status Flow

GET /account-requests/{AccountRequestId}

Account Request Status

DELETE /account-requests/{AccountRequestId}

Data Model

Account Requests - Request

UML Diagram

Data Dictionary

Account Requests - Response

UML Diagram

Data Dictionary

Usage Examples

Setup Account Request - All Permissions Granted

Status - AwaitingAuthorisation

Status - Authorised

Delete Account Request

Setup Account Request with Limited Permissions