This documentation is for WSO2 Open Banking version 1.3.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 on separate servers. 

Before you begin

  1. Create a user with Internal/creator and Internal/publisher roles using https://<WS02_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.
  2. Set endpoints in the velocity_template.xml file.
  3. Configure sequence files.

Configuring the velocity_template.xml 

Make sure to update the <WS02_OB_KM_HOST>  in the consent enforcement handler, as given below in the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file, before creating the APIs. 

<handler class="">
    #if($!apiVersion == "v3.0" || $!apiVersion == "v3.1")
    <property name="accountValidationUrl" value="https://<WS02_OB_KM_HOST>:9446/consent/uk300/accounts-validation"/>
    <property name="paymentConsumtionUpdateUrl"
    <property name="paymentSubmissionValidationUrl"
    <property name="paymentConsentDataUrl"
    <property name="fundConfirmationValidationUrl"
    #elseif($!apiVersion == "v2.0")
    <property name="accountValidationUrl" value="https://<WS02_OB_KM_HOST>:9446/consent/uk200/accounts-validation"/>
    <property name="paymentSubmissionValidationUrl"
    <property name="accountValidationUrl" value="https://<WS02_OB_KM_HOST>:9446/consent/uk110/accounts-validation"/>
    <property name="paymentSubmissionValidationUrl"
    <property name="keyStore" value="./repository/resources/security/wso2carbon.jks"/>
    <property name="password" value="wso2carbon"/>
    <property name="alias" value="wso2carbon"/>

Configuring the sequence files

Sequence files for Accounts, Payment, and CoF must be updated separately in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ <Name of the API>. Change the <WSO2_OB_KM_HOST> and <WSO2_OB_APIM_HOST> hostnames to the accurate hostnames as mentioned follows:

  • Change the <WSO2_OB_KM_HOST> of the following configuration, which is under the <filter regex=".*\/account-access-consents.*" source="$ctx:endpointURI"> filter:

    <header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300" />
  • Change the <WSO2_OB_APIM_HOST> of the following configuration, which is under the <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION"> filter:

    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/accounts/accountservice" />
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/accounts/accountservice" />
  • Change the <WSO2_OB_KM_HOST> of the following configuration, which is under the <filter source="get-property('routeToBackend')" regex="false"> filter:

    <header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/payments"/>
  • Change the <WSO2_OB_APIM_HOST> of the following configurations, which is under the <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION"> filter:

    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/payments/paymentservice"/>
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/payments/paymentservice"/>
  • Change the <WSO2_OB_KM_HOST> of the following configuration, which is under the <filter regex=".*\/funds-confirmation-consents.*" source="$ctx:endpointURI"> filter:

    <header name="To" value="https://localhost:9446/consent/uk300" />
  • Change the <WSO2_OB_APIM_HOST> of the following configurations, which is under the <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION"> filter:

    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
     <header name="To" value="https://localhost:9443/open-banking/services/fundsConfirmation/fundsconfirmationservice" />
     <header name="To" value="https://localhost:9443/open-banking/services/fundsConfirmation/fundsconfirmationservice" />

By default, WSO2 Open Banking API Manager includes a mock bank backend, which is configured by default in the In sequences. Ideally, the two occurrences of https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/accounts/accountservice 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.

Configuring TokenAPI.xml and AuthorizeAPI.xml 

Make sure that the following handlers are in TokenAPI.xml and AuthorizeAPI.xml files in <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api

  <handler class=""/>

Displaying the error response for access token failures in the UK error format

This is available only as a WUM update and is effective from September 23, 2019 (09-23-2019). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

Add the following configuration to the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/auth_failure_handler.xml under the <sequence key="_cors_request_handler_"/> configuration to display the error response for access token failures in the UK error format.

<filter source="get-property('REST_API_CONTEXT')" regex=".*\/(pisp|aisp|cbpii).*">
			<class name=""/>

Create and publish an API

In the WSO2 Open Banking UK v3.1, it is mandatory to configure APIs for:

  • Accounts API v3.1
  • Payments API v3.1
  • Confirmation of Funds (CoF) API v3.1

Follow the steps given below to create and publish an API.

  • Create a user with Internal/creator and Internal/publisher roles in order to configure the API. For more information on creating a user, refer Configuring users and roles.
  • If an API is already deployed with a previous version, 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.

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 ( https:// <WSO2_OB_APIM_HOST>:9443/publisher ) with the credentials for .

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

  3. Select the Swagger definition from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis and configure the properties according to the open-banking specification. Find more information from the table given below.

    Click Start Creating.
  4. Click Next: Implement to navigate to the next level.
  5. Expand Managed API, and use the table below to select the relevant Endpoint Type from the drop-down list.
  6. Check Select a message mediation policy to be executed in the message flow under Message Mediation Policies.
  7. Click Upload In Flow and select the corresponding In sequence file from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis.

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

  9. Expand Throttling Settings. Under Subscription Tiers, check the option as Unlimited : Allows unlimited requests unless you want to limit the requests.
  10. Expand API Properties and add the following values as Additional properties. Click the + button to save the values.

    Property Name


    Property Value


    Configure the open banking specification and the API type for the DCR API you deploy as follows:

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

     Click here to see how to configure

    Add the following Additional properties based on the API you're publishing. Click the + button to save each property. 


    Property Name

    Property Value
    AccountInfo API v3.1.1ob-specuk
    Payments API v3.1.1ob-specuk
    Funds Confirmation API v3.1.1ob-specuk
    Event Notifications API v3.1.0ob-specuk
    Dynamic Client Registration API v3.2ob-specuk

    Set the value of the ob-api-version property according to the version of the API. See the version mentioned in the swagger file.

    For example:

  11. Click Save & Publish.

Summarized information for configuring APIs - UK specification

APIImplement tabManage tab
Endpoint typeEndpointEnable Message mediation

In flow

API property nameAPI property value
AccountInfo API v3.1.1DynamicN/AMark as checked


Payments API v3.1.1DynamicN/AMark as checked <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ ob-specuk
Funds Confirmation API v3.1.0DynamicN/AMark as checked


ob-spec uk
Event Notifications API v3.1.0


N/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ ob-specuk

Dynamic ClientRegistration API v3.2

DynamicN/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ ob-api-type dcr

This is available only as a WUM update and is effective from March 26, 2019 (03-26-2019). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

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.

    Users need to 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.1 version of Payment Initiation API.

  5. Click on 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.

  • No labels