This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Accounts Information Service Provider Flow v1.3

Owned by Former user (Deleted)
Last updated: Oct 15, 2020 by Former user (Deleted)
30 min read

This document explains the flow of events related to the Account Information Service (AIS) that an Accounts Information Service Provider (AISP) tries. For the Berlin specific solution, AIS is exposed as an API resource in  NextGenPSD2XS2AFramework - 1.3.3 of WSO2 Open Banking. In the Account Information Service;

  1. TPP can access/retrieve account information of PSUs (Payment Servicing Users).

  2. PSUs can authorise the TPPs to access/retrieve their account, transactions, and balances information.

Before you begin,

You need to deploy the  Account Information  API in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.3/psd2-api_1.3.3_20190412.yaml file. Click here to see how to deploy APIs for WSO2 Open Banking Berlin.


Users can test the Account Information Service in WSO2 Open Banking using the following steps that are described below.

Step 1 - Sign up as a TPP

In this step, the TPP registers its TPP application in WSO2 API store.

 Click here to see how it is done...

  1. Navigate to the API Store at https://<WSO2_OB_APIM_HOST>:9443/store.

  2. Select Sign-up that is on the top left corner of the homepage.

  3. Provide the requested details on the Sign Up page.

     Click here for more information..

    a. Generic details:

    Field

    Description

    Username/Email

    The username/email that the TPP uses to sign in to the API Store.

    Password

    The password that the TPP uses to sign in to the API Store.

    Retype Password

    This is to prevent the TPP from accidentally setting an incorrect password.

    Last Name

    This is the last name of the TPP.

    First Name

    This is the first name of the TPP.


    b. Company details:

    Field

    Description

    Legal Entity Name

    The official name of the TPP.

    Country of Registration

    The country in which the TPP is registered.

    Legal Identifier Number (LEI)

    This identifies the TPP.

    Company Register

    The organization that registered the TPP.

    Company Registration Number

    Identifier issued at the TPP registration.

    Address Line 1

    Address of the TPP.

    Address Line 2

    Address of the TPP.

    City

    City in which the TPP is located.

    Postal Code

    Postal code of the geographical location of the TPP.

    Country

    The country in which the TPP is located.


    c. Competent authority registration details:

    Field

    Description

    Competent Authority

    The regulatory body that authorises and supervises the open banking services delivered by the TPP.

    Competent Authority Country

    Country of the competent authority that authorised the TPP to provide open banking services.

    Competent Authority Registration Number

    The registration number issued by the Competent Authority to the TPP.

    URL of the Competent Authority Register Page

    URL of the page that has the list of organizations authorised by the competent authority.

    Open Banking Roles

    Captures the open banking roles the TPP is willing to take up:

    • Account Information Service Provider: An Account Information Service Provider (AISP) provides an aggregated view of all the accounts and past transactions that a customer has with different banks. To provide this view to the customer, the AISP should have authorisation from the customer to view the corresponding transaction and balance information of all the accounts. The AISPs can also provide the facility to analyze the customer's spending patterns, expenses, and financial needs. Unlike a PISP, an AISP cannot transfer funds from a account.

    • Initiation Service Provider: A Initiation Service Provider (PISP) initiates credit transfers on behalf of a bank's customer.

    After selecting the TPP, indicate whether the TPP is authorised by a competent authority to provide the services of the selected roles.

    If the TPP is not yet registered to provide the services of the selected roles, indicate whether the TPP has applied for registration or not.

  4. Read terms and conditions. Click the checkbox to agree to the terms and conditions.

  5. Click Sign Up. A request to approve the TPP sign up is now sent to the Approver users.


Step 2 - Approve the TPP

Now that you have signed up as a TPP, an admin who overlooks all TPP sign-up forms must approve it. 


It is not mandatory to include the approval step for approving the TPP. In order to add this step, you need to configure workflows in the WSO2 Open Banking solution. For more information on configuring workflows, see /wiki/spaces/OB140/pages/29393938.  

 Click here to see how it is done...

  1. Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.

  2. Locate the approval request and click Assign To Me.

  3. Click Start to start the approval process.
  4. Select Approve then Complete.

Now the TPP can sign in to the API store. 

Step 3 - Sign in to the API store as the TPP

Users can sign in to the API store and proceed with the steps mentioned below.

 Click here to see how it is done...

  1. Sign in to the API Store as the TPP at https://<WSO2_OB_APIM_HOST>:9443/store.

  2. Click Sign In and navigate to the Sign In page.

  3. Enter the username and the password you entered when signing up as a TPP.

  4. Click Sign In . 

The homepage of the API store is now displayed along with the APIs.

Step 4 - Create an application

The TPP needs to create an application in WSO2 API store that represents its TPP application. The application created via WSO2 API store allows to observe statistics of APIs, subscribe to APIs, and generate keys for the subscribed APIs.

 Click here to see how it is done...

  1. In the API store, click Applications.

  2. Click Add Application .

  3. Enter application details.

    Field

    Description

    Name

    Application name.

    Per Token Quota

    Determines the maximum number of API requests accepted within a given duration.

    Description

    This describes the purpose of the application.

  4. Click Add. 

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

Step 5 - Subscribe to API

The TPP user needs to subscribe to the NextGenPSD2XS2AFramework - 1.3.3 API in order to access API resources. Once subscribed to the NextGenPSD2XS2AFramework - 1.3.3 API, the users are subscribing to all the supported services of Accounts, Payments and Confirmation of Funds API resources. 


 Click here to see how it is done...

  1. In the API store, Click APIs.

  2. Select the NextGenPSD2XS2AFramework-1.3.3 API.

  3. In the right top corner, select the application you created from the dropdown list under Applications.

  4. Set the Tiers to Unlimited.

  5. Click Subscribe .

Now that you have subscribed to the API, you can generate keys and invoke the API.

Step 6 - Create and upload certificates

The TPP user needs to obtain an eIDAS certificate from a Qualified Trust Service Provider (QTSP) that validates whether the TPP is registered in a governing entity. It is verified in the TPP Onboarding process. 

For testing purposes, WSO2 Open Banking provides a sample eIDAS certificate. To download the sample eIDAS certificate, click here. 

Upload the downloaded sample eIDAS certificate to the client trust stores of WSO2 OB APIM and WSO2 OB KM.

    • Locate the client trust stores in WSO2 OB APIM and WSO2 OB KM in the following directory paths:

      • <WSO2_OB_APIM>/repository/resources/security/client-truststore.jks
      • <WSO2_OB_KM>/repository/resources/security/client-truststore.jks

  • Use the following command to upload the certificate:

    keytool -import -trustcacerts -alias <<alias>> -file <<path_to_sample_eIDAS_cert>> -keystore <<path_to_truststore>> -storepass wso2carbon -noprompt

Step 7 - Generate keys

The TPP user requests client ID and client secret to access the subscribed APIs.

 Click here to see how it is done...

  1. Sign in to the API store as the TPP user and click either of the following on the Applications tab.

    1. Production Keys: Generates access tokens in the production environment.

    2. Sandbox Keys : Generates access tokens in the sandbox environment.

  2. Provide the requested information as defined below:  

    Field

    Description

    Grant Types

    These determine the credentials that are used to generate 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.

    • Code: This relates to the authorisation code grant type and is applicable when consuming the API as a user.

    Client ID

    OrganizationIdentifier as provided in the EIDAS certificate. The organizationIdentifier attribute contains information using the following structure in the presented order:

    • PSD as the 3-character legal person identity type reference;

    • 2-character ISO 3166 country code representing the NCA country;

    • hyphen-minus (-)

    • 2-8 character NCA identifier (A-Z upper case only, no separator)

    • hyphen-minus (-)

    • PSP (Payment Service Provider) identifier (authorisation number as specified by NCA)

    Callback URL

    This is the URL used by the Account Information Service Provider (AISP) / Payment Initiation Service Provider (PISP) 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

    According to the Berlin specification, the TPPs require to upload eIDAS (electronic identification and trust services) certificate when generating the keys. If you do not have an eIDAS certificate, you can create an X.509 certificate to generate the keys.

     Click here to see how it is done...

    1. A keystore file is used to store the trusted certificates of the TPP in the WSO2 Open Banking solution. Use the commands given below in a command-line interface in order to create a keystore file as the TPP.

      Make sure to update the following placeholders:

      <alias>A preferred alias for the keystore file.
      <filename>A preferred name for the keystore file.
      keytool -genkey -alias <alias> -keyalg RSA -keystore <filename>.jks

      During the command execution, the TPP user requires to;


      1. Set a password for the keystore.
      2. Provide information, acquired when registering with a governing entity.
      3. Set a password for user-defined alias (<alias>).

    2. Convert the keystore from the .jks format to .PKCS12.  Make sure to update the following placeholders:

      <keyStoreName>This is the name of the <filename>, given above.
      <PKCS12FileName>This is the name of the keystore in the .PKCS12 format.
      keytool -importkeystore -srckeystore <keystoreStoreName>.jks -destkeystore <PKCS12FileName>.p12 -deststoretype PKCS12

      During the command execution, the TPP user requires to;

      1. Set a password for the destination keystore.
      2. Enter the source keystore password, as defined in the above step.

    3. Create the application certificate (.pem) file in the PKCS12 format using the keystore. e.g: tpp.p12.

      Make sure to update the following placeholders:

      <PKCS12FileName>This is the name of the keystore in the PKCS12 format, as mentioned above for the <PKCS12FileName>.
      <PEMFileName>This is the name of the application certificate that is created in the .pem format. 
      openssl pkcs12 -in <PKCS12FileName>.p12 -nokeys -out <PEMFileName>.pem

      During the command execution, the TPP user requires to;

      1. Set a password to import the .pem file.

    You can now upload the eIDAS certificate or X.509 certificate by clicking Choose Files.

    Make sure to add only the content between BEGIN CERTIFICATE and END CERTIFICATE strings from the certificate file.

  3. Click Request Access if you are generating production keys. If workflows are configured in the solution, it sends a request to Approver user to approve the token generation. Otherwise, it generates consumer key and consumer secret.

  4. Click Generate Keys if you are generating sandbox keys. It generates consumer key and consumer secret.

  5. Now, you have generated the consumer key and consumer secret successfully. Navigate to the first point of Authorization code that appears after the keys on the same page.

    This is the URL that the TPP must send to the PSU. This URL points to a web interface with permissions that the TPP is seeking from the PSU. A sample web interface looks as follows:


Step 8 - Approve Production Key generation

This step includes instructions to an Approver user to review and approve a request to generate production keys for an application.

It is not mandatory to include the approval step for the Production Key generation. In order to add this step, you need to configure workflows in the WSO2 Open Banking solution. For more information on configuring workflows, see /wiki/spaces/OB140/pages/29393938.

 Click here to see how it is done...

  1. Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.

  2. Click Tasks and then the Application Registration .

  3. Locate the approval request and click Assign To Me .

  4. Click Start to start the approval process.
  5. Select Approve and then click Complete.
  6. Navigate back to the API Store and click Applications.
  7. On the Applications tab, Click View of the application that you created.
  8. Click Production Keys tab to find the generated keys.

  9. It includes the consumer key and consumer secret as follows:

    Note that consumer key is used as client ID in the below steps.


Step 9 - Generate application access token

When invoking APIs, application access tokens must be generated using the client credential grant type. The generated application access token is used to invoke the NextGenPSD2XS2AFramework-1.3.3 API.

 Click here to see how it is done...

  1. Generate the client assertion by signing the following JSON payload using the supported algorithms. The supported algorithms are RS256 and PS256.

    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:
    1. Sign in to the Identity and Access Management console at  https://localhost:9446/carbon . 
    2. In the Main menu, go to Home > Identity > Identity Providers > Resident.
    3. 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://localhost:8243/token .

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

    curl -v POST \
 https://<WSO2_OB_APIM_HOST>:8243/token \
 --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
 -H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" \
 -d "client_id=<CLIENT_ID>&grant_type=client_credentials&scope=accounts+openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<CLIENT_ASSERTION_JWT>&redirect_uri=<APPLICATION_CALLBACK_URL>" 

    The access token is now generated.


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


Step 10 - 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 / consents - Create consent

First, the TPP must state the accounts and permissions in the account initiation request and send it to the bank. Then, the bank responds with a URL that redirects the PSU to provide the consent for the accounts that the TPP wishes to access. The request and the response are as follows:

Users can call any API resource at any time once the TPP creates a consent, and PSUs grant access to relevant accounts.

 Click here to find the consent related API calls that can be invoked at any time...

GET /consents/{consentId} - Get consent request

The TPP can retrieve information of the account initiation request using the following request. It generates a sample response as below:

GET / consents/{consentId}/status - Consent status request

Once the consent is granted by the PSU, the TPP can retrieve the status of the consent using the sample request given below. It generates a sample response as follows:

DELETE /consents/{consentId} - Delete consent

The TPP can delete a consent that PSU has granted. See below for a sample request and response:

Step 11 - Initiate an authorisation flow for an account consent

WSO2 Open Banking for Berlin Implementation supports both implicit and explicit authorization flows for account authorization. In both cases, TPP generates the authorization URL using the well-known configuration that is received from the ASPSP as scaOAuth link in the response.

Implicit authorisation

In this approach,

  1. ASPSP creates authorization sub-resources after the account consent is received
  2. ASPSP replies with the well-known configuration of the Identity and Access Management module in the links section of the response
  3. TPP generates the authorization URL using the well-known URL
  4. PSU goes through the authorisation flow with that authorisation URL

Explicit authorisation

In this approach,

  1. TPP initiates the authorization flow by invoking the POST /consents/{consentId}/authorisations API resource
  2. At this point, the ASPSP creates authorization sub-resources and reply with the well-known configuration of the Identity and Access Management module in the links section of the response
  3. TPP has to generate the authorization URL, which the PSU uses to go through the authorization flow later
  4. The TPP invokes the  POST /consents/{consentId}/authorisations  API resource to authorise a particular account
  5. The TPP generates the authorisation URL using the well-known URL under scaOAuth link in the response


 Click here to see how it is done...

POST /consents/{consentId}/authorisations - Start the authorisation process for a consent

The sample request shown below is seeking access to PSU's account. In this case, the TPP is creating an authorisation subresource, that the PSU can use to authorise.

Users can call any API resource at any time once the TPP creates a consent, and PSUs grant access to relevant accounts.

 Click here to find the consent related API calls that can be invoked at any time...

Following API resources can be followed by the consent authorisation step mentioned here.

GET /consents/{consentId}/authorisations - Get Consent Authorisation Sub-Resources Request

The TPP can use GET / consents/{consentId}/authorisations API resource to retrieve the list of subresource IDs that are created. A sample request and response are given below:

GET /consents/{consentId}/authorisations/{authorisationId} - Read the SCA (Strong Customer Authentication) status of the consent authorisation

The TPP can check the status of a particular authorisation using the sample request given below:

Authorisation URL
The TPP uses the well-known URL regardless of the authorisation followed (Implicit/Explicit) to authorise an account as below:


 Click here to see how it is done...

  • The open banking solution sends the authorisation URL that was generated under scaOAuth link of the response. The response the TPP uses differs according to the authorisation as follows:

    Implicit authorisationThe response the TPP gets when initiating an account consent.
    Explicit authorisationThe response the TPP gets when invoking POST /consents/{consentId}/authorisations API resource.

    A sample well-known URL under scaOAuth parameter looks as below:

    {
   "scaOAuth":{
      "href":"https://<WSO2_OB_APIM_HOST>:8243/.well-known/openid-configuration"
   }
}

  • Paste the authorisation URL in the web browser. The format for the authorisation URL looks as follows:

    Sample URL Format
    https://<WSO2_OB_APIM_HOST>:8243/authorize/?scope=<YOUR_SCOPES>&response_type=code&redirect_uri=<REDIRECT_URI>&state=<DYNAMICALLY_SET_VALUE>&code_challenge_method=<YOUR_CODE_CHALLENGE_METHOD>&client_id=<ORGANIZATION_ID>&code_challenge=<YOUR_CODE_CHALLENGE>

    Use the following table to find the descriptions for the parameters:

    ParameterDescription

    scope

    		This is the reference to the consent resource for account access. It is in the form of ais:<consentId>
    response_typecode is recommended.
    redirect_uriThe TPP's URI that the OAuth2 server redirects the PSU's user agent after the authorisation.
    statePrevents XSRF attacks by TPP setting a dynamic value.

    code_challenge_method

    		Code verifier transformation method. It is recommended in the Berlin specification to use S256.
    client_idAs provided in the eIDAS certificate, the organization_Identifier must contain the following information in it: - "PSD" as 3 character legal person identity type reference - 2 character ISO 3166 country code representing the NCA country - hyphen-minus "-" and - 2-8 character NCA identifier (A-Z uppercase only, no separator - hyphen-minus "-" - PSP identifier (authorization number as specified by NCA)

    code_challenge

    		This is used to avoid code injection attacks using the PKCE challenge in the cryptographic RFC 7636. Go to https://tools.ietf.org/html/rfc7636 for more information on the cryptographic RFC 7636.

  • The authorisation URL points to a web interface as follows:

  • Upon the user approving or denying the account consent, the user can invoke consent/authorization API resource of the authentication endpoint. By invoking this API resource, the user retrieves the consent approval/denial, that is displayed on the consent web-app.


Step 12 - Generate user access token

The TPP must obtain a user access token to invoke the APIs mentioned under Invoke Account Information Service APIs section.

 Click here to see how it is done...

Use the following sample request in order to generate the user access token:

 See below for the sample request and response used in this step...

Step 13 - Invoke Account Information Service APIs

Following are the API functionalities available for the Account Information Service in 1.3.3:

GET /accounts - Read account lists

The user can retrieve a list of accounts of a PSU. Following are the sample request and the response to call Get /accounts API resource.

GET /accounts/{account-id} - Read account details

The user can retrieve details of an account that consent is already granted by the PSU and stored in the ASPSP system. Use the sample request to generate a sample response as given below.

GET /accounts/{account-id}/balances - Read balances

The user can retrieve account data for a consent-granted account. Use the sample request to generate a sample response as follows:

The account addressed by the account-id is constant until the consent granted to that specific account expires.

GET /accounts/{account-id}/transactions - Read transaction list of an account

The user can retrieve transaction reports and transaction lists for a consent-granted account using the sample request given below. Users can choose the type of transaction using the booking status parameter. For a given account, a user can specify dateFrom and dateTo parameters.

GET /accounts/{account-id}/transactions/{transactionId} - Read transaction details

The user can retrieve transaction information for a specific transaction. The path of xxx is denoted under _links subfield in the response generated by calling the G ET / accounts/{account-id}/balances API resource.

This call generates responses for the transactions that are reported in the JSON format.

Use the sample request and generate a response as follows:

GET /card-accounts - Read a list of card accounts

The TPP can retrieve a list of card accounts. You can specify PSU ID to check the card-accounts that the PSU have consented. Additionally, you can retrieve balances of card accounts in the response. See below for a sample request and response.

GET /card-accounts/{account-id} - Read details of a card account

Retrieves information of a specific card account that the PSU has consented. See below for sample request and response information:

GET /card-accounts/{account-id}/balances - Read balances of card accounts

The TPP can retrieve balance information for a specific account by calling this API resource.

GET /card-accounts/{account-id}/transactions - Read transaction list of a card account

The TPP can retrieve a list of transactions of a card account that the PSU has consented. Sample request and response look as follows: