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

Event Notification API v3.1.2

Owned by Former user (Deleted)
Last updated: Oct 09, 2020
16 min read

This is available only as a WUM update and is effective from June 10, 2020 (06-10-2020). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

This document explains the flow of events related to the Event Notification API v3.1.2. 

Before you begin:

You need to configure and deploy the Event Notification APIs. 

 Click here to see how it is done...
  1. Configuring the Event Notification API:
    1. Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file.
    2. Update the following configurations and restart the servers.
      • <TokenIssuer>: The URL from where the token is issued.
      • <NotificationExpiryTime>: The expiry time of the notification, in seconds.
      • <NotificationAPIUrl>: The URL of the event-notification endpoint which is exposed from API Manager.
      • <NumberOfSetsToReturn>: The maxEvents parameter in the polling request informs the ASPSP how many notifications the TPP wants to retrieve at a moment. When the maxEvents parameter is absent in the polling request,  NumberOfSetsToReturn defines this value.
      •  <SigningAlias>: The alias of the certificate that signs the notifications sent from ASPSP to TPP.  
      <EventNotifications>
	<IsEnabled>true</IsEnabled>
	<TokenIssuer>www.openbank.com</TokenIssuer>
	<NotificationExpiryTime>180</NotificationExpiryTime>
	<NotificationAPIUrl>https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/event-notification</NotificationAPIUrl>
	<NumberOfSetsToReturn>5</NumberOfSetsToReturn>
	<SigningAlias>wso2carbon</SigningAlias>
</EventNotifications>
  2. Deploying the Event Notification API:

You can configure APIs through the API Publisher by signing in as a user whose role includes Internal/publisher. Follow the steps given below:

    1. Sign in to the API Publisher at https://<WSO2_OB_APIM_HOST>:9443/publisher.

    2. Click ADD NEW API > I have an existing API. 

    3. Select the relevant Swagger file from the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Notifications/3.1.2 directory. For more information, see the table below.

    4. Click Start Creating.
    5. Click Next: Implement to navigate to the next level.
    6. Expand  Managed API  and select endpoint from the drop-down list. For more information, see the table below.
    7. Check Select a message mediation policy to be executed in the message flow under Message Mediation Policies.

    8. Click Upload In Flow and select the relevant In sequence file from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Notifications/3.1.2  directory. For more information, see the table below.

    9. Click Next: Manage to navigate to the next level.

    10. Expand Throttling Settings. Under Subscription Tiers, check the option as Unlimited : Allows unlimited requests unless you want to limit the requests.

    11. Expand API Properties and add the following values as Additional properties:

      Property Name

      		Property Value

      ob-spec

      		 uk
      ob-api-typeevent
      ob-api-version3.1.2
    12. Click the + button to save the above values.
    13. Click Save & Publish

Summarized information for configuring APIs

APIImplement tabManage tab
Endpoint typeEndpoint (Production/Sandbox)Enable Message mediation

In Flow / Out Flow


API property nameAPI property value
Event Notification Subscription API v3.1.2

Dynamic

N/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Notifications/3.1.2/event-subscriptions-dynamic-endpoint-insequence-3.1.2.xml
ob-specuk
ob-api-typeevent
ob-api-version3.1.2

Aggregated Event Polling API v3.1.2

HTTP/REST Endpointhttps://<WSO2_OB_APIM_HOST>:9446/event-notifications/uk300/Mark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Notifications/3.1.2/aggregated-polling-dynamic-endpoint-insequence-3.1.2.xml
ob-specuk
ob-api-typeevent
ob-api-version3.1.2

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 payment 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 payment account.

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

    • Payment Instrument Issuer Service Provider (PIISP)/ Card Based Payment Instrument Issuer (CBPII) : A Card Based Payment Instrument Issuer issues card-based payment instruments that can be used to initiate a payment transaction from a payment account held with another payment service provider

    Set the role as Account Information Service Provider (AISP) or Payment Initiation Service Provider (PISP). 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.

 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 with an AISP application needs to create an application using WSO2 API store. The application created via WSO2 API store allows to observe statistics of APIs, subscribe to APIs, and access the subscribed APIs.
 Click here to see how it is done...

  1. Go to the Applications tab in the API Store.

  2. Click Add Application.

  3. Enter application details.

    Field

    Description

    Name

    Name of the application.

    Per Token Quota

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

    Regulatory Compliance

    Determines whether this application handle regulatory compliance APIs. By default, this box is checked. 

    Description

    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 both Event Notification Subscription and Aggregated Event Polling APIs to complete the Even Notification flow. Once subscribed, the users can access all the supported services of these API resources.


 Click here to see how it is done...

  1. Go to the APIs tab in the API Store.

  2. Click the EventSubscriptionsAPI - v3.1.2 thumbnail and select the API.

  3. Select the application you created in the Create an application section. 

  4. Set the throttling policy to Unlimited.

  5. Click Subscribe.

  6. In the Subscription Succesful message, select Stay on this page. 
  7. Click the Go Back button.
  8. Now you are in the API Store Listing page. Click the AggregatedEventPollingAPI - v3.1.2 thumbnail and select the API. 
  9. Follow step 3, 4 and 5 and subscribe to the Aggregated Event Polling API using your application.

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

Step 6 - Create and upload certificates

The TPP user needs to create certificates to validate whether the TPP is registered in a governing entity. 

You can also create a self-signed certificate the following instructions given below and try out the API flow:

 Click here to see a self-signed certificate is created...

In order to use self-signed certificates as mentioned in the below steps, disable the <CertificateRevocationValidationEnabled> configuration under <CertificateManagement> in the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml and <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml files.

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

 Once you create a self-signed certificate, upload it 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_HOME>/repository/resources/security/client-truststore.jks
    • <WSO2_OB_KM_HOME>/repository/resources/security/client-truststore.jks

  • Use the following command to upload the self-signed certificate:

    keytool -import -alias <alias> -keystore cacerts -file <PEMFileName>.pem

Step 7 - Generate keys

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

 Click here to see how it is done...

  1. Sign in to the API store as a 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 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.

  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.

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.

 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 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 in the API Store, 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:

Step 9 - Generate application access token

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

 Click here to see how it is done...

  1. Once the client is successfully registered, sign in to the API Store and go to the Applications tab.

  2. Select your client application from the Application List. Click View of the application that you created.

  3. Choose the Production Keys or Sandbox Keys tab based on your environment.

  4. The Consumer Key shown above is the client ID of your application.

  5. Generate the client assertion by signing the following JSON payload using the supported algorithms.

    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 .

  6. 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 '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 10 - Create an event-subscription resource

POST /event-subscriptions 

The TPP requests the ASPSP to create a new event-subscription resource using this API endpoint. On successful creation, the ASPSP responds with a unique EventSubscriptionId to refer to the resource. The TPP uses this resource to access event notifications.

 Click here to see the other endpoints

GET /event-subscriptions

The TPP requests the ASPSP to retrieve its event-subscription resource.

PUT /event-subscriptions/{EventSubscriptionId}

The TPP to requests the ASPSP to update an event-subscription resource.

DELETE /event-subscriptions/{EventSubscriptionId}

The TPP requests the ASPSP to delete an event-subscription resource.

Step 11 - Invoke Aggregated Event Polling API

POST /events

The endpoint allows a TPP to poll for, acknowledge, and receive event notifications. The TPPs communicate their polling parameters and event notification acknowledgements using this endpoint. The ASPSP responds accordingly, sending event notifications as indicated by the TPP's polling parameters.

The TPPs are able to perform the following using the POST /events endpoint using different payloads:

  • Poll for events
  • Acknowledge the received events
  • Poll for new events and acknowledge the received events at once


The TPPs send two polling parameters to indicate the polling behaviours:

  • returnImmediately: Indicates whether an ASPSP should return a response immediately or provide a long poll. 

    Long polling is currently not supported by WSO2 Open Banking. Therefore, the value of returnImmediately is always true.

  • maxEvents: The maximum number of events to be returned. A value of zero indicates the ASPSP should not return events even if available. The upper bound value of the parameter depends on the size of the payload and the connection. If maxEvents is not defined in the payload, the ASPSP sets the value according to the <NumberOfSetsToReturn> configuration in  <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml.


Given below is a sample request where the TPP is requesting for a response immediately, only to make sure there are events available. 

The TPP confirmed that there are events. For example, if there are 5 events available with the ASPSP and the TPP wants to receive only 3 events, the request looks as follows:

Now the TPP acknowledges the received events (both positive and negative acknowledgements) while accepting more events. As per the response, there are more events available with the ASPSP. The TPP continues requesting for events until there are no more events and the value of moreAvailable is false.