Account and Transaction API v3.1.5

This document explains the flow of events related to the Account and Transaction API v3.1.5.

Before you begin:

To enable Request-URI validation during the account retrieval process; validate the account ID against the account ID in the consent, open the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml file and set the following property to true and restart the Identity and Access Management server:
```
[open_banking.account_id_validation_on_retrieval]
enable = true
```
You need to deploy the Account and Transaction API, to try out the flow.
Click here to find how to deploy the API...
1. Sign in to the API Publisher Portal (https://<WSO2_OB_APIM_HOST>:9443/publisher) with creator/publisher privileges.
2. In the APIs tab, select CREATE NEW API > I Have an Existing REST API .
3. Set the Input Type to OpenAPI File .
4. Click BROWSE FILE TO UPLOAD and select the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Accounts/3.1.5/ account-info-swagger-3.1.5.yaml file.
5. Click Next.
6. Set the Context value as follows:
  If you are using WSO2 Open Banking API Manager Level 2.0.0.114 or above:
  
  If you are configuring an API of v3.1.8 or above, set the following context value manually.
  /open-banking/{version}/aisp
7. Leave the Endpoint field empty as it is.
8. Set the business plan to Unlimited: Allows unlimited requests unless you want to limit the requests.
9. Click Create to create the API.
10. Once you get the message that the API is successfully updated, go to Endpoints using the left menu panel.
11. Select Dynamic Endpoints and click Save.
12. Go to Runtime Configurations using the left menu panel.
13. Click the edit button under Request > Message Mediation.
14. Now, select the Custom Policy option.
15. Upload the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Accounts/3.1.5/accounts-dynamic-endpoint-insequence-3.1.5.xml file and click SELECT.
16. Scroll down and click SAVE.
17. Now, go to Properties using the left menu panel.
18. Click Add New Property.
19. Add the following properties and click the Add button to save the values.
  Property Name
  Property Value
  ob-spec uk
  ob-api-type account
  ob-api-version 3.1.5
20. Click SAVE.
21. Go back to Overview using the left menu panel.
22. Click PUBLISH.
23. The published Accounts and Transaction API is available in the Developer Portal at https://<WSO2_OB_APIM_HOST>:9443/devportal.

If you have integrated with OBIE you can use the Dynamic Client Registration v3.2 API. Once you deploy the DCR v3.2 API, you can continue from the Generate application access token step.

Step 1 - Sign up as a TPP
Step 2 - Sign in to the Developer Portal as the TPP
Step 3 - Create an application
Step 4 - Subscribe to API
Step 5 - Create and upload certificates
Step 6 - Generate keys
Step 7 - Generate application access token
Step 8 - Initiate account consents
Step 9 - Authorizing account consents
Step 10 - Generate user access token
Step 11 - Invoke Account and Transaction APIs

Step 1 - Sign up as a TPP

In this step, the TPP registers its TPP application in the WSO2 Open Banking Developer portal.

Click here to see how it is done...

Navigate to the WSO2 Open Banking Developer portal at https://<WSO2_OB_APIM_HOST>:9443/devportal.
Go to the Applications tab in the Developer Portal.
In the Sign-in form, click Create Account.
Provide a username and click Proceed Self Register.
Fill the Create New Account form to complete registration.
Read terms and conditions. Click the checkbox to agree to the terms and conditions.
Click Register.

Step 2 - Sign in to the Developer Portal as the TPP

Users can sign in to WSO2 Open Banking Developer portal with the authentication details created during sign up.

Click here to see how it is done...

Sign in to the Developer portal as the TPP at https://<WSO2_OB_APIM_HOST>:9443/devportal.
Enter the username and the password you entered when signing up as a TPP.
Click Continue.

The homepage of the Developer portal is now displayed along with the published APIs.

Step 3 - Create an application

The TPP with an AISP application needs to create an application using WSO2 Open Banking Developer portal. The application created via the Developer portal allows to observe statistics of APIs, subscribe to APIs, and access the subscribed APIs.

Click here to see how it is done...

Go to the Applications tab in the Developer Portal.
Click ADD NEW APPLICATION.
Enter application details.

WSO2 Open Banking currently authenticates the TPP applications using the Reference (Opaque) method.
Click SAVE.

An application can be used to subscribe to multiple APIs. See Subscribe to an API for the instructions.

Step 4 - Subscribe to API

The TPP user needs to subscribe to the Account and Transaction API in order to access the API resources. Once subscribed, the users can access all the supported services of the API resources.

Click here to see how it is done...

Go to the APIs tab in the Developer portal.
Select the Account and Transaction API.
Go to Subscriptions at the bottom of the API and select SUBSCRIBE.
Select Application from the drop-down list, set the Throttling Policy and click SUBSCRIBE.
Once you subscribe, you can find the list of subscriptions in the bottom.

Now that you have subscribed to the API, generate access tokens and invoke the API.

Step 5 - Create and upload certificates

The TPP user needs to create certificates to validate whether the TPP is registered in a governing entity. It is verified in the TPP Onboarding process. There are two types of certifications that can be added to the client trust stores of the WSO2 Open Banking Identity and Access Management and WSO2 Open Banking API Management modules.

Root and issuer certificates obtained from Open Banking Implementation Entity.
eIDAS issuer certificates obtained from the Qualified Trust Service Providers.

See eIDAS Implementation for PSD2 Compliance to find out more information on the two approaches.

In order to support eIDAS or OB certificates in WSO2 Open Banking, you need to update the client trust stores.

Click here to see how it is done...

Step 6 - Generate keys

The TPP user requires a Client ID(Consumer Key) to access the subscribed APIs.

Click here to see how it is done...

Sign in to WSO2 Open Banking Developer portal as a TPP user.
Go to the Applications tab and select the application you used to subscribe to the Confirmation of Funds API.
Scroll down and select either of the following types of keys:
1. Production Keys: Generates access tokens in the production environment.
2. Sandbox Keys: Generates access tokens in the sandbox environment.
Click Manage at the bottom of the application.

Provide the requested information as defined below:

Field

Description

Grant Types

These determine the credentials that are used to generate the access token.

Code: This relates to the authorisation code grant type and is applicable when consuming the API as a user.
Implicit: This is similar to the code grant type, but instead of generating code, this directly provides the access token.
Refresh Token: This is to renew an expired access token.
Client Credential: This relates to the client credentials grant type and is applicable when consuming the API as an application.

Callback URL

This is the URL used by the TPP to receive the authorisation code sent from the Account Servicing Payment Service Provider (ASPSP), e.g: bank. The authorisation code can be used later to generate an OAuth2 access token.

Application Certificate

This is the content between the BEGIN CERTIFICATE and END CERTIFICATE strings of the application certificate (.PEM) that you created above.

If you have configured the OB certificates, for testing purposes, you can use the sample application certificate available here.

Click GENERATE KEYS to generate production or sandbox keys. It generates consumer key and consumer secret.

Step 7 - Generate application access token

When invoking APIs in the Account and Transaction flow, application access tokens must be generated using the client credential grant type. The generated application access token is used to invoke the Account and Transaction API.

Click here to see how it is done...

You can skip the above steps and use DCR v3.2 API to dynamically register the clients.

Once the client is successfully registered, sign in to WSO2 Open Banking Developer Portal and go to the Applications tab.
Select your client application from the Application List.
You can view the keys you generated at the bottom of this page:
The Consumer Key shown above is the client ID of your application.
Generate the client assertion by signing the following JSON payload using the supported algorithms.

If you have configured the OB certificates, you may use the attached certificate and keys for signing and transports layer security testing purposes.
The value of the aud claim should contain the same value as the Identity Provider Entity ID.
Click here to view the Identity Provider Entity ID:
Sign in to the Identity and Access Management console at https://<WSO2_OB_IAM_HOST>t:9446/carbon.
In the Main menu, go to Home > Identity > Identity Providers > Resident.
View the value in Resident Identity Provider > Inbound Authentication Configuration > OAuth2/OpenID Connect Configuration > Identity Provider Entity ID. By default this value is set to https://<WSO2_OB_APIM>:8243/token.

Run the following cURL command in a command prompt to generate the access token. Update the placeholders with the relevant values.

curl POST \
  https://<WSO2_OB_APIM_HOST>:8243/token \ 
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
   -d 'client_id=<CLIENT_ID>&grant_type=client_credentials&scope=accounts%20openid%20&client_assertion=<CLIENT_ASSERTION_JWT>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&redirect_uri=<APPLICATION_CALLBACK_URL>'

The access token is now generated.

You can use the same cURL command to regenerate the access token.

Step 8 - Initiate account consents

In this step, the TPP creates a request to get the consent of the PSU to access the accounts and its information from the bank. The Bank sends the request to the PSU stating the accounts and information that the TPP wishes to access. Upon the user approving or denying the account consent, the TPP is now eligible to access the user's account details.

Click here to see how it is done

POST/ account-access-consents

This resource creates an account access consent. Use the following format in the request body.

{
   "Data":{
      "Permissions":[
         "ReadAccountsDetail",
         "ReadBalances",
         "ReadBeneficiariesDetail",
         "ReadDirectDebits",
         "ReadProducts",
         "ReadStandingOrdersDetail",
         "ReadTransactionsCredits",
         "ReadTransactionsDebits",
         "ReadTransactionsDetail",
         "ReadOffers",
         "ReadPAN",
         "ReadParty",
         "ReadPartyPSU",
         "ReadScheduledPaymentsDetail",
         "ReadStatementsDetail"
      ],
      "ExpirationDateTime":"2020-10-11T10:28:49.599+05:30",
      "TransactionFromDateTime":"2020-10-06T10:28:49.600+05:30",
      "TransactionToDateTime":"2020-10-09T10:28:49.600+05:30"
   },
   "Risk":{
      
   }
}

Fill in the following mandatory field:
- Authorization - An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Enter the application access token, you generated from the above step.

A sample request and response follows the format given below.
- The response contains the ConsentId.

GET/ account-access-consents/{ConsentId}

An AISP may retrieve an account-access-consent resource that they have created to check its status. In order to make this request, the AISP must have an access token issued by the ASPSP using a client credentials grant.
Fill in the mandatory fields:
ConsentId - The unique id of the consent which you want to retrieve.
Authorization - An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Enter the application access token, you generated from the above step.

A sample request is in the format below.

curl GET \
  https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/aisp/account-access-consents/<CONSENT_ID> \
  -H 'x-fapi-financial-id: open-bank' \
  -H 'Authorization: Bearer <APPLICATION_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'charset: UTF-8' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH>

Following is a sample response.

{
    "Meta": {
        "TotalPages": 1
    },
    "Risk": {},
    "Links": {
        "Self": "https://localhost:8243/open-banking/v3.1/aisp/account-access-consents/41042513-fa45-4da8-93be-1513b3caffac"
    },
    "Data": {
        "Status": "Authorised",
        "StatusUpdateDateTime": "2020-10-07T12:46Z",
        "CreationDateTime": "2020-10-07T09:29Z",
        "TransactionToDateTime": "2020-10-09T10:28:49+05:30",
        "ExpirationDateTime": "2020-10-11T10:28:49+05:30",
        "Permissions": [
            "ReadAccountsDetail",
            "ReadBalances",
            "ReadBeneficiariesDetail",
            "ReadDirectDebits",
            "ReadProducts",
            "ReadStandingOrdersDetail",
            "ReadTransactionsCredits",
            "ReadTransactionsDebits",
            "ReadTransactionsDetail",
            "ReadOffers",
            "ReadPAN",
            "ReadParty",
            "ReadPartyPSU",
            "ReadScheduledPaymentsDetail",
            "ReadStatementsDetail"
        ],
        "ConsentId": "41042513-fa45-4da8-93be-1513b3caffac",
        "TransactionFromDateTime": "2020-10-06T10:28:49+05:30"
    }
}

DELETE/ account-access-consents/{ConsentId}

If the PSU revokes consent to data access with the AISP, the AISP must delete the account-access-consent resource. In order to make this request, the AISP must have an access token issued by the ASPSP using a client credentials grant.
Fill in the mandatory fields:
- ConsentId - The unique id of the consent which you want to delete.
- Authorization - An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Enter the application access token, you generated from the above step. Use the following format and replace the placeholders.

Given below is a sample request.

curl DELETE \
  https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/aisp/account-access-consents/<CONSENT_ID> \
  -H 'x-fapi-financial-id: open-bank' \
  -H 'Authorization: Bearer 0895e677-9f13-3ce3-84f4-46113f9048be' \
  -H 'Accept: application/json' \
  -H 'charset: UTF-8' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> 
  -d '{
   "Data":{
      "Permissions":[
         "ReadAccountsDetail",
         "ReadBalances",
         "ReadBeneficiariesDetail",
         "ReadDirectDebits",
         "ReadProducts",
         "ReadStandingOrdersDetail",
         "ReadTransactionsCredits",
         "ReadTransactionsDebits",
         "ReadTransactionsDetail",
         "ReadOffers",
         "ReadPAN",
         "ReadParty",
         "ReadPartyPSU",
         "ReadScheduledPaymentsDetail",
         "ReadStatementsDetail"
      ],
      "ExpirationDateTime":"2020-10-11T10:28:49.599+05:30",
      "TransactionFromDateTime":"2020-10-06T10:28:49.600+05:30",
      "TransactionToDateTime":"2020-10-09T10:28:49.600+05:30"
   },
   "Risk":{
      
   }
}'

If the deletion is successful you will get a 204 No Content response.

Step 9 - Authorizing account consents

The AISP redirects the bank customer to authenticate and approve/deny application-provided consents.

Click here to see how it is done

Generate the request object by signing the following JSON payload using the supported algorithms.

Run the following in a browser to prompt the invocation of the authorize API. Make sure you update the placeholders with the relevant values:

https://<WSO2_OB_APIM_HOST>:8243/authorize/?response_type=<RESPONSE_TYPE>&client_id=<APPLICATION_ID>&scope=accounts%20openid&redirect_uri=<APPLICATION_REDIRECT_URI>&state=YWlzcDozMTQ2&request=<REQUEST_OBJECT>&prompt=login&nonce=<REQUEST_OBJECT_NONCE>

You are directed to a login page. Log in with the credentials of a user that has a subscriber role.
If a secondary factor is required, e.g. SMSOTP, provide the relevant values. Upon successful authentication, the user is redirected to the consent management page.
Upon providing consent, an authorization code is generated.

Step 10 - Generate user access token

In this section, you will be generating an access token using the authorization code generated in the section above.

Click here to see how it is done

The client_assertion is a JSON Web Token (JWT). Generate the client_assertion by signing the following JSON payload using the supported algorithms:
Run the following cURL command in a command prompt to generate the access token as a TPP user:
```
curl POST \https://<WSO2_OB_APIM_HOST>:8243/token \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
-d 'grant_type=authorization_code&scope=openid accounts&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=<CLIENT_ASSERTION>&redirect_uri=<APPLICATION_REDIRECT_URI>&code=<CODE_GENERATED>client_id=<APPLICATION_ID>'
```
The response contains an access token and a refresh token.
The access tokens have an expiration period, once an access token expires, you need to regenerate it. Run the following cURL command to generate a new access token as an AISP:
curl POST \ https://<WSO2_OB_APIM_HOST>:8243/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'cache-control: no-cache' \ --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \ -d 'grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_id=4hZILATfPyXlLFqkP3Z0OBYhmDwa&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=<CLIENT_ASEERTION>'

Step 11 - Invoke Account and Transaction APIs

Following API functionalities are available in the Account and Transaction API.

GET/ accounts

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

An AISP will be given the full list of accounts that the PSU has authorised the AISP to access. The AccountIds returned is used to retrieve other resources for a specific AccountId.

GET/ accounts/{AccountId}

The AISPs are able to retrieve the account information for a given AccountId. The AccountID is retrieved in the call to GET/ accounts.

GET/ balances

The AISPs are able to retrieve the account information resources in bulk.

This retrieves the resources for all authorised accounts linked to the account request.

GET/ accounts/{AccountId}/balances

The AISPs are able to retrieve the account balance information resource for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ transactions

The AISPs are able to retrieve the transactions in bulk.

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

GET/ accounts/{AccountId}/transactions

The AISPs are able to retrieve the transaction resource for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ beneficiaries

The AISPs are able to retrieve the beneficiaries' information in bulk.

This endpoint will retrieve the beneficiaries' resources for all authorised accounts linked to a specific account request.

GET/ accounts/{AccountId}/beneficiaries

The AISPs are able to retrieve the account beneficiaries information resource for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ direct-debits

The AISPs are able to retrieve direct-debits for all accounts that the PSU has consented to.

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

GET/ accounts/{AccountId}/direct-debits

The AISPs are able to retrieve the direct-debits for a specific account identified by AccountId using this endpoint. The AccountId is retrieved in the call to GET/ accounts.

GET/ standing-orders

The AISPs are able to retrieve the standing orders' resources in bulk.

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

GET/ accounts/{AccountId}/standing-orders

The AISPs are able to retrieve the standing-order resources for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ products

The AISPs are able to retrieve the products information in bulk.

This endpoint will retrieve the products resources for all authorised accounts linked to a specific account request.

GET/ accounts/{AccountId}/product

The AISPs are able to retrieve the account product information for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ offers

The AISPs are able to retrieve the offers resources in bulk. This will retrieve the resources for all authorised accounts linked to the account request.

GET/ accounts/{AccountId}/offers

The AISPs are able to retrieve the offers resource for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ party

The AISPs are able to retrieve details on the user that has authorised the account-access-consent with the ASPSP:

In the case of a business account, this will be the details of the party that has given authorisation to the AISP to view the account
In the case of a joint account, this will be the party that has given authorisation to the AISP to view the account

GET/ accounts/{AccountId}/party

The AISPs are able to retrieve details on the account owner or holder for a given AccountId.

In the case of a business, this will be the details of the business
In the case of a joint account, this will be the party that has given authorisation to the AISP to view the account

GET/ accounts/{AccountId}/parties

The AISPs are able to retrieve details on the account owners or holders and operators. The AccountId is retrieved in the call to GET/ accounts.

GET/ scheduled-payments

The AISPs are able to retrieve the scheduled-payments resources in bulk.

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

GET/ accounts/{AccountId}/scheduled-payments

The AISPs are able to retrieve the scheduled-payments for a specific AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ statements

The AISPs are able to retrieve statement information for all accounts that the PSU has consented to.

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

GET/ accounts/{AccountId}/statements

The AISPs are able to retrieve the statements information resource for a given AccountId. The AccountId is retrieved in the call to GET/ accounts.

GET/ accounts/{AccountId}/statements/{StatementId}

The AISPs are able to retrieve the statement information resource for a specific statement in the AccountId.The AccountId is retrieved in the call to GET/ accounts.

GET/ accounts/{AccountId}/statements/{StatementId}/file

The AISPs are able to retrieve a non-json representation of a specific statement as specified in the Accept header by the AISP. The statement can be downloaded in formats such as pdf, doc and csv.

Given below is a sample request:

curl -X GET \
  https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1.2/aisp/accounts/<AccountId>/statements/<StatementId>/file \
  -H 'Authorization: Bearer <USER_ACCESS_TOKEN>' \
  -H 'Cache-Control: no-cache' \
  -H 'accept: application/pdf' \
  --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
  --output statement.pdf

GET/ accounts/{AccountId}/statements/{StatementId}/transactions

The AISPs are able to retrieve the transaction resources for a specific AccountId and a StatemntId.

Property Name	Property Value
`ob-spec`	`uk`
`ob-api-type`	`account`
`ob-api-version`	`3.1.5`