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 on separate servers. 

 


Configuring the velocity_template.xml 

Make sure to update the <WSO2_OB_KM_HOST> parameter in the consent enforcement handler of the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file, before creating the APIs. 

<handler class="com.wso2.finance.open.banking.uk.consent.enforcement.ConsentEnforcementHandler">
    #if($!apiVersion == "v3.0" || $!apiVersion == "v3.1" || $!apiVersion == "v3.1.1")
    <property name="accountValidationUrl" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/accounts-validation"/>
    <property name="paymentConsumtionUpdateUrl"
              value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/payments/{PaymentType}/{ConsentId}/status/{Status}"/>
    <property name="paymentSubmissionValidationUrl"
              value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/payment-submission-validation"/>
    <property name="paymentConsentDataUrl"
              value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/payments/{PaymentType}/{ConsentId}/Consumption"/>
    <property name="fundConfirmationValidationUrl"
              value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/funds-confirmation-validation"/>
    #elseif($!apiVersion == "v2.0")
    <property name="accountValidationUrl" value="https://<WSO2_OB_KM_HOST>::9446/consent/uk200/accounts-validation"/>
    <property name="paymentSubmissionValidationUrl"
              value="https://<WSO2_OB_KM_HOST>:9446/consent/uk110/payment-submission-validation"/>
    #else
    <property name="accountValidationUrl" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk110/accounts-validation"/>
    <property name="paymentSubmissionValidationUrl"
              value="https://<WSO2_OB_KM_HOST>:9446/consent/uk110/payment-submission-validation"/>
    #end
    <property name="keyStore" value="./repository/resources/security/wso2carbon.jks"/>
    <property name="password" value="wso2carbon"/>
    <property name="alias" value="wso2carbon"/>
</handler>

To enable Mutual Transport Layer Security, you need to add the following handlers to <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml: 

  • MTLSValidationHandler
  • MTLSClientTokenValidationHandler
  • MTLSCertValidationHandler

It is also mandatory to add the above-mentioned handlers in order to run the security conformance suite successfully. See Mutual Transport Layer Security (MTLS) for instructions.


Configuring sequence files

In order to update the In Sequence file for the Accounts, Payment, and Confirmation of Funds APIs, update the relevant XML file from the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/<Name of the API>/<version of the API> directory.

Update the <WSO2_OB_KM_HOST> and <WSO2_OB_APIM_HOST> placeholders with the hostname of the WSO2 OB KM and APIM servers respectively.

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.

  • Change the <WSO2_OB_KM_HOST> of the following configuration:

    <filter regex=".*\/account-access-consents.*" source="$ctx:endpointURI">
    	<header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300" />
  • Change the <WSO2_OB_APIM_HOST> of the following configuration:

    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
    	<then>
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/accounts/accountservice" />
    	</then>
    	<else>
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/accounts/accountservice" />
    	</else>
  • Change the <WSO2_OB_KM_HOST> of the following configuration:

    <filter source="get-property('routeToBackend')" regex="false">
    	<header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300/payments"/>
    


  • Change the <WSO2_OB_APIM_HOST> of the following configurations:

    <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
    	<then>
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/payments/paymentservice"/>
    	</then>
    	<else>
    		<header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/payments/paymentservice"/>
    	</else>
    </filter>
  • Change the <WSO2_OB_KM_HOST> of the following configuration:

    <filter regex=".*\/funds-confirmation-consents.*" source="$ctx:endpointURI">
    	<header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/uk300" />
  • Change the <WSO2_OB_APIM_HOST> of the following configurations:

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

By default, a mock backend is configured in the In Sequence file of the API Manager instance in WSO2 Open Banking. Ideally, the two occurrences of https://<WSO2_OB_APIM_HOST>:9443/open-banking/services/accounts/accountservice under the <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION"> parameter should be replaced by the core banking system's API endpoints corresponding to the production and sandbox environments respectively. For more information on how to integrate a core banking system, see Integrating Core Banking System.


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

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).*">
		<then>
			<class name="com.wso2.finance.open.banking.gateway.uk.AuthFailureResponseCreationMediator"/>
			<respond/>
		</then>
</filter>


Create and publish an API

In WSO2 Open Banking for UK, you can configure the following APIs:

  • Accounts API 
  • Payments API 
  • Confirmation of Funds API 

If you have already deployed v3.1 APIs:

According to OBIE, the v3.1 and v3.1.x APIs have the same context values. Therefore, if you have already deployed v3.1 APIs, the v3.1.x APIs cannot be deployed as new versions of existing APIs. You have to update the swagger file content.

 Click here to see how it is done
  • Sign in to the API Publisher (https://<WSO2_OB_APIM_HOST>:9443/publisher).
  • Edit relevant v3.1.x API.

  • You are redirected to the Design phase. Click the Edit Source button under API Definition section.
  • In the Swagger Editor menu bar, select File>Import File.
  • Browse for the intended v3.1.x API in <WSO2_OB_APIM_HOME>repository/resources/finance/apis/openbanking.org.uk/<API_NAME>/3.1.x directory and click Open File.
  • Click Apply Changes to save the changes and go back to the Design page.
  • Scroll down and click Save.

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 .

  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. Add the following Additional properties based on the API you're publishing. Click the + button to save each property. 

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

    Given below are sample values for v3.1.1 APIs. Update the property values according to the API version that you're deploying.

    API

    Property Name

    Property Value
    AccountInfo API v3.1.1ob-specuk
    ob-api-typeaccount
    ob-api-version3.1.1
    Payments API v3.1.1ob-specuk
    ob-api-typepayment
    ob-api-version3.1.1
    Funds Confirmation API v3.1.1ob-specuk
    ob-api-typecof
    ob-api-version3.1.1
    Event Notifications API v3.1.0ob-specuk
    ob-api-typeevent
    ob-api-version3.1.0
    Dynamic Client Registration API v3.2ob-specuk
    ob-api-typedcr
    ob-api-version3.2

  11. Click Save & Publish.

Summarized information for configuring APIs - UK specification

This summary table contains sample values for v3.1.1 APIs. Use relevant insequence files in respective directories and the API property values according to the APIs that you're deploying.

APIImplement tabManage tab
Endpoint typeEndpointEnable Message mediation

In Flow / Out Flow


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

<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Accounts/3.1.1/accounts-dynamic-endpoint-insequence-3.1.1.xml

ob-specuk
ob-api-typeaccount
ob-api-version3.1.1
Payments API v3.1.1DynamicN/AMark as checked <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Payments/3.1.1/payments-dynamic-endpoint-insequence-3.1.1.xmlob-specuk
ob-api-typepayment
ob-api-version3.1.1
Confirmation of Funds API v3.1.1DynamicN/AMark as checked

<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/FundsConfirmation/3.1.1/funds-confirmation-dynamic-endpoint-insequence-3.1.0.xml

ob-spec uk
ob-api-typecof
ob-api-version3.1.1
Event Notifications API v3.1.0

Dynamic

N/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Notifications/3.1.0/notifications-dynamic-endpoint-insequence-3.1.0.xmlob-specuk
ob-api-typeevent
ob-api-version3.1.0

Dynamic Client Registration API v3.2

DynamicN/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/DynamicClientRegistration/3.2/dcr-dynamic-endpoint-insequence-3.2.xmlob-specuk
ob-api-typedcr
ob-api-version3.2

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/openbanking.org.uk/Accounts/3.1.0 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.

Request payload validation

Request payload validation adds flexibility to validate an incoming request against any customisations done to the swagger definition. For example, remove an enumeration from an existing set and check whether the incoming request contains the defined enumerations. 

According to the following sample payload, the given account number formats are accepted.

If your API supports only the UK.OBIE.IBAN and UK.OBIE.SortCodeAccountNumber account number formats, you can 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 com.wso2.finance.open.banking.api.executor.OBAPIPublisherExecutor. 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

  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