This documentation is for WSO2 Open Banking version 1.5.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

This document guides you with the assumption that you have set up WSO2 Open Banking Key Manager, and WSO2 Open Banking API Manager in separate servers. 

Configuring the velocity_template.xml file

The <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file checks the deployed specification. It is by default configured to support berlin specification with the following handlers. 

Replace the <WSO2_OB_KM_HOST> placeholder with the hostname of your Open Banking Key Manager server.

#if($apiObj.additionalProperties.get("ob-spec") == "berlin")
## add ob-berlin specific handlers before the APIManagerExtensionHandler
<handler class=""/>
<handler class="">
    <property name="accountValidationUrl" value="https://<WSO2_OB_KM_HOST>:9446/consent/berlin110/accounts-validation"/>
    <property name="keyStore" value="./repository/resources/security/wso2carbon.jks"/>
    <property name="password" value="wso2carbon"/>
    <property name="alias" value="wso2carbon"/>
## end of Berlin-specific handlers

Configuring the sequence file

The <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ file contains in sequences for accounts, payments and confirmation of funds APIs.

  • The <WSO2_OB_KM_HOST> placeholders in this file need to be replaced by the hostname of your WSO2 Open Banking Key Manager server.
  • The WSO2 Open Banking API Manager includes a mock bank backend which is configured by default in the in sequences. Ideally, the occurrences of https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/<API_NAME> should be replaced by the core banking system's API endpoints corresponding to the production and sandbox environments respectively. 

    For more information, see Integrating Core Banking System for Berlin

If you are using the following deployment options, update the placeholders as follows:

Replace the <WSO2_OB_KM_HOST> and <WSO2_OB_APIM_HOST> placeholders with the IP addresses of the puppet agents that run WSO2 OB KM and APIM respectively.

Replace the <WSO2_OB_KM_HOST> and <WSO2_OB_APIM_HOST> placeholders with the hostnames of WSO2 OB KM and APIM in the Docker network respectively.

For example, if you use our Docker Compose resources without any modifications, the placeholder values are obkm and obam.

Replace the <WSO2_OB_KM_HOST> and <WSO2_OB_APIM_HOST> placeholders with the names of the internal services related to the deployment of WSO2 OB KM and APIM respectively.

For example, if you use the Kubernetes resources for WSO2 Open Banking - Deployment pattern 1 without any modifications, the placeholder values are https://wso2ob-pattern-1-obam-service and https://wso2ob-pattern-1-obkm-service.

For deployment patterns, see Open Banking API Manager High Availability Deployment.

<sequence xmlns="" name="dynamic-endpoint-insequence-1.3.3.xml">
    <property name="endpointURI" expression="get-property('To')"/>

    <switch source="$ctx:endpointURI">
        <case regex=".*payments.*">
            <header name="TPP-Unique-ID" scope="transport" expression="get-property('api.ut.consumerKey')"/>
            <filter source="$ctx:endpointURI" regex=".*authorisations.*">
                    <header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/authorisation"/>
                    <filter source="get-property('api.ut.HTTP_METHOD')" regex="POST">
                            <header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/payments"/>
                            <filter source="$ctx:endpointURI" regex="^((?!\/bulk-payments).)*$">
                                    <payloadFactory media-type="json">
                                            <arg evaluator="json" expression="$"/>
                            <property name="resourcePath" scope="default" type="STRING" value=""/>
                            <property expression="get-property('resourcePath')" name="REST_URL_POSTFIX" scope="axis2"

                            <header name="To"
                                    expression="fn:concat('https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/payments', get-property('api.ut.resource'))"/>
        <case regex=".*/accounts.*">
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
        <case regex=".*/card-accounts.*">
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
        <case regex=".*/consents.*">
            <filter source="$ctx:endpointURI" regex=".*authorisations.*">
                    <header name="To" value="fn:concat('https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/authorisation/accounts', get-property('api.ut.resource'))"/>
                    <property action="remove" name="REST_URL_POSTFIX" scope="axis2"/>
                    <header name="To" expression="fn:concat('https://<WSO2_OB_KM_HOST>:9446/consent/berlin130' , get-property('api.ut.resource'))"/>
                    <header name="TPP-Unique-ID" expression="get-property('api.ut.consumerKey')" scope="transport"/>
                    <header name="App-ID" expression="get-property('')" scope="transport"/>
                            <action type="replace" regex="\/consents" value="\/accounts" fragment="path"/>
        <case regex=".*/funds-confirmations.*">
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/cof"/>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/cof"/>
    <property name="ENDPOINT_ADDRESS" expression="get-property('To')"/>

Configuring an API

WSO2 Open Banking Berlin has the NextGenPSD2XS2AFramework-1.3.3 API which contains the v1.3 resource for Accounts, Payments and Confirmation of Funds flows. The swagger definition for this API is available in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/

Given below is the procedure to configure and publish the NextGenPSD2XS2AFramework-1.3.3 API. 

Before you begin

  • Create a user with Internal/creator and Internal/publisher roles using https://<WSO2_OB_KM_HOST>:9446/carbon. To create users and roles, see configuring users and roles, which elaborates the steps to create the user as the API publisher.
  • If one version of the API is already deployed, you may create a new version of it instead of deploying a new API. For more information, see Create a new version for an existing API.
  1. Sign in to the API Publisher https:// <WSO2_OB_APIM_HOST> :9443/publisher .

  2. Click ADD NEW API.

  3. Select I Have an Existing API option.

  4. Select the Swagger File option and browse for the swagger definition by clicking on the Browse button. Select the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ file.

  5. Click Start Creating.

  6. You are directed to the Design API stage. Design General Details are loaded for you in the Design tab.

    You need to set the context value as xs2a

  7. Click Next: Implement to navigate to the next level.
  8. Expand Managed API, and set Endpoint Type by selecting Dynamic Endpoint from the drop-down list.
  9. Check Select a message mediation policy to be executed in the message flow under Message Mediation Policies.
  10. Click Upload In Flow and select the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ In sequence file.

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

  12. Under Subscription Tiers, check the option Unlimited : Allows unlimited requests unless you want to limit the requests.
  13. Expand API Properties and add the following as Additional properties

    Property NameProperty Value
  14. Click the + button to save the values.

  15. Click Save & Publish.

  16. The published API is available in the API Store at https://<WSO2_OB_APIM_HOST>:9443/store.

Summarized information for configuring APIs 

APIImplement tabManage tab
Endpoint typeEndpointEnable Message mediation

In flow

API property nameAPI property value
NextGenPSD2XS2A Framework - 1.3.3DynamicN/AMark as  checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ ob-specberlin

Create a new version for an existing API

In the API Publisher of WSO2 Open Banking, users are not allowed to duplicate the scope of an API. Therefore, users are allowed to create a new version for the API in order to share the same scope. See below to find how it is done:

  1. In the API Publisher (https://<WSO2_OB_APIM_HOST>:9443/publisher), click the API thumbnail to view the API overview.
  2. Select the CREATE NEW VERSION tab.

  3. Follow the versioning format and define the new version.

  4. Click Done.

    Define the correct version for the API and choose the swagger and In sequence files appropriately.

    The directory path to the files in the solution pack helps you to choose the correct file. For example, choose the swagger and in sequence files from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ if you want to create the 3.1.0 version of Payment Initiation API.

  5. Select the newly created API and click EDIT API.
  6. You are redirected to the Design phase. Click the Edit Source button under API Definition section.
  7. In the Swagger Editor menu bar, select File>Import File.
  8. Browse for the intended swagger file in .yaml format and click Open File.
  9. Click Apply Changes to save the changes and go back to the Design page.
  10. Scroll down and click Save.
  11. Click Next: Implement > to navigate to the next page.
  12. Expand Managed API, and click Upload In Flow.
  13. Select the relevant In sequence file for the corresponding API and its version, and click Upload.
  14. Click Next: Manage > to navigate to the next page.
  15. Expand API Properties and ensure the ob-spec property is set to reflect the correct specification.
  16. Click Save & Publish.

    To get the existing subscriptions to the new version, follow the steps below:

    1. In the API Publisher, click the new API thumbnail to Browse API.
    2. Go to the Lifecycle tab.
      Tick the relevant boxes if you want to:
      1. Deprecate the old versions after publishing this new version.
      2. Remove the existing subscriptions and require the applications to re-subscribe.
    3. Click Publish.
    4. To verify the subscriptions, go to the Versions tab.

Configure the FrequenyPerDay throttling policy

The FrequencyPerDay value is sent in the consent initiation request body to indicate the requested maximum frequency for access without PSU involvement per day. According to the NextGenPSD2 XS2A framework, the FrequencyPerDay value needs to be checked when the PSU's IP address is not sent in an API invocation request.

For one-off access, this attribute has to be set to '1'. The frequency has to be greater than or equal to 1.

Use the below instructions to configure the FrequencyPerDay throttling policy:

  1. Open <WSO2_OB_APIM_HOME>/repository/conf/api-manager.xml.

    1. Make sure that the throttling is enabled for Data Publisher under the <DataPublisher> attribute of <ThrottlingConfigurations>:

    2. Change the value of the <Username> attribute under <TrafficManager> according. By default, it looks as follows: 

      <!--Required in OB-->
      <Username>[email protected]@carbon.super</Username>
    3. Change the value of te <connectionfactory.TopicConnectionFactory> attribute under <JMSConnectionParameters> according. By default, it looks as follows: 

      <!--Required in OB-->
  2. Make sure that the FrequencyPerDay property is enabled in <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml as follows:

  3. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/<publisher-name>--NextGenPSD2XS2AFramework_v1.xml file and place CustomThrottlingPolicyHandler before ThrottleHandler as follows:

    <handler class=""/>
    <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.ThrottleHandler"/>
  4. Deploy the throttling policy located in <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/wso2-obam-conf/FrequencyPerDayPolicy as
    a custom throttling policy in the admin portal of WSO2 Open Banking API Manager:

    1. Sign in to the Admin Portal using the URL (https://<WSO2_OB_APIM_HOST>:9443/admin) and your admin credentials.
    2. ClickThrottling Policies tab and click Custom Policies tab.

    3. Enter the information for the custom policy accordingly.

      • Name the custom policy as "FrequencyPerDayPolicy".
      • For Key Template, use the following format: $customProperty.accountId:$userId:$appId.
      • Copy the content from the policy in <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/wso2-obam-conf/FrequencyPerDayPolicy and paste it under Siddhi Query.

Request payload validation

Request payload validation adds flexibility to validate an incoming request against any customisations done to the swagger definition. For example, modify the currency property in the API swagger and then the solution will validate the incoming request against the updated currency value. Simply modify the published swagger file and republish the API for the modifications to take effect.

When an API is published, the swagger file is added as a local entry and saved under the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/local-entries directory.

To add the swagger as a local entry, the created and published API lifecycles are extended using customised API executor named For more information on executors, see Extension Points of API Life cycle.  

If you modify the Swagger after publishing the API, republish the API to apply the swagger based validations. 

 Click here to see how to republish an API

 Therefore, follow the steps below:

  1. Sign in to the API Publisher at https://<WSO2_OB_APIM_HOST>:9443/publisher using the credentials of a user, whose role is an API Publisher. For more information on users and roles, see here.
  2. Select the respective API and click Edit API.
  3. You are redirected to the  Design  phase. Click the  Edit Source button  under  API Definition  section.
  4. Click  Apply Changes to save the changes and go back to the  Design  page.
  5. Scroll down and click Save.
  6. Click Next: Implement > Next: Manage and Save and Publish.

  • No labels