Integrating with the Core Banking System for Berlin

This document outlines, the integration effort required to integrate WSO2 Open Banking with Berlin Group NextGenPSD2 1.3 APIs. Following topics guide the user through required configurations.

The sample requests and responses below explain the information passing from the WSO2 Open Banking solution to the bank and what is expected from the bank as the response.

Payment service user authorisation flow integration

With the introduction of Berlin Group v1.3 APIs, authorisation service was set in place that facilitates multi-level SCA (multiple authorizers on one consent) and authorisation cancellations. WSO2 Open Banking also supports bank offered consent, which gives the ability for the PSU to select accounts in the authorisation flow.

Sharable Accounts API
The Shareable Accounts API is used for two purposes as follows.
- Validate the debtor account if the PISP sends it in the initiation request
- Populate the payment accounts on the consent page if the initiation request does not contain a debtor account.
The backend endpoint for shareable accounts retrieval can be configured in the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file. A sample endpoint configuration is given below:
```
<SharableAccountsRetrieveEndpoint>http://<BANK_BACKEND>:9763/open-banking/services/bankaccounts/bankaccountservice/sharable-accounts</SharableAccountsRetrieveEndpoint>
```
The userId (PSU ID) must be sent in the URL as a query parameter when calling this API when listing the accounts.
Request
```
GET /shareable/{userId}
Content-Type: application/json
Accept: application/json
```
Response
```
{
  "accounts": [
    {
      "iban": "DE12345678901234567890",
      "bban": "BARC12345612345678",
      "pan": "5409050000000000"
    }
  ]
}
```

Retrieve user list for a given account list

This API retrieves the users for a given accounts list. It validates the accounts and identifies the authorisation parties for the consent. This API is used in the authorisation flow to control the status of the authorisation.

Request

POST /accounts/users/ 
Accept: application/json
Content-Type: application/json

{
  "accounts": [
    {
      "iban": "DE12345678901234567890",
      "bban": "BARC12345612345678",
      "pan": "5409050000000000"
    }
  ]
}

Response

{
  "accounts": [
    {
      "identification": {
        "iban": "DE12345678901234567890",
        "bban": "BARC12345612345678",
        "pan": "5409050000000000"
      },
      "users": [
        {
          "customerIdentification": "JEAN123",
          "userIdentification": "jean.luc.picard@enteprise.org"
        }
      ]
    }
  ]
}

Account Information Service flow integration

In WSO2 Open Banking, AISP flow integration with the core banking system is utilized during account information retrieval requests.

The URL of the API endpoints of the core banking system, which corresponds to the account's information retrieval requests, should be configured in the In sequences of the Accounts API. For more information, see Configuring sequence files.

In the Open Banking accounts flow, the WSO2 Open Banking solution manages the lifecycle of the consent.

The banks are required to provide the account information to the Third Party Providers(TPPs) using the following resources (See section “6 AccountInformationService” in Implementation Guideline).

HTTP Method	Resource	Description
GET	/accounts	Reads accounts list
GET	/accounts/{accounts-id}	Reads accounts’ details
GET	/accounts/{accounts-id}/balance	Reads the balance of an account
GET	/accounts/{accounts-id}/transactions	Reads a list of transactions of an account
GET	/accounts/{accounts-id}/transactions/{transactionsId}	Reads transaction details
GET	/cardaccounts	Reads card accounts list
GET	/cardaccounts/{accounts-id}	Reads card accounts’ details
GET	/cardaccounts/{accounts-id}/balance	Reads the balance of a card account
GET	/cardaccounts/{accounts-id}/transactions	Reads a transactions list of a card account

When the TPP makes account information retrieval requests, the WSO2 Open Banking solution validates the consent request, and upon successful validation, the consent-related information is directed to the core banking system in the form of a header. If required, the core banking system can perform further consent validations using this header.

Request

GET /accounts
Account-Consent-Information: eyJhbGciOiJSUzUxMiJ9.eyJhY2NvdW50Q29uc2VudEluZm
psuId: YWRtaW5Ad3NvMi5jb21AY2FyYm9uLnN1cGVy

Account-Request-Information

A signed JSON Web Token(JWT) which contains the user consent. This needs to be decoded by the core banking system.

Account-Consent-Information: eyJhbGciOiJSUzUxMiJ9.eyJhY2NvdW50Q29uc2VudEluZm8iOiJ7XCJhY2NvdW50Q29uc2VudEluZm9cIjp7XCJhY2Nlc3NcIjp7XCJiYWxhbmNlc1wiOlt7XCJpYmFuXCI6XCJERTQwMTAwMTAwMTAzMzA3MTE4NjA4XCJ9LHtcImliYW5cIjpcIkRFMDIxMDAxMDAxMDkzMDcxMTg2MDNcIixcImN1cnJlbmN5XCI6XCJVU0RcIn0se1wiaWJhblwiOlwiREU2NzEwMDEwMDEwMTMwNjExODYwNVwifV0sXCJhY2NvdW50c1wiOlt7XCJpYmFuXCI6XCJGUjQwMTAwMTAwMTAzMzA3MTE4NjA4XCJ9XSxcInRyYW5zYWN0aW9uc1wiOlt7XCJpYmFuXCI6XCJERTQwMTAwMTAwMTAzMzA3MTE4NjA4XCJ9LHtcIm1hc2tlZFBhblwiOlwiMTIzNDU2eHh4eHh4MTIzNFwifV19LFwiY29tYmluZWRTZXJ2aWNlSW5kaWNhdG9yXCI6dHJ1ZSxcInZhbGlkVW50aWxcIjpcIjIwMTktMDctMTBcIixcInJlY3VycmluZ0luZGljYXRvclwiOnRydWUsXCJmcmVxdWVuY3lQZXJEYXlcIjo0fSxcImFjY291bnRMaXN0XCI6W3tcImlzQmFsYW5jZVBlcm1pc3Npb25cIjpudWxsLFwiaWJhblwiOlwiREU0MDEwMDEwMDEwMzMwNzExODYwOFwifSx7XCJpc0JhbGFuY2VQZXJtaXNzaW9uXCI6bnVsbCxcImliYW5cIjpcIiBERTAyMTAwMTAwMTA5MzA3MTE4NjAzXCJ9LHtcImlzQmFsYW5jZVBlcm1pc3Npb25cIjpudWxsLFwiaWJhblwiOlwiIERFNjcxMDAxMDAxMDEzMDYxMTg2MDVcIn0se1wiaXNCYWxhbmNlUGVybWlzc2lvblwiOm51bGwsXCJpYmFuXCI6XCJGUjQwMTAwMTAwMTAzMzA3MTE4NjA4XCJ9LHtcImlzQmFsYW5jZVBlcm1pc3Npb25cIjpudWxsLFwiaWJhblwiOlwiIERFNDAxMDAxMDAxMDMzMDcxMTg2MDhcIn0se1wiaXNCYWxhbmNlUGVybWlzc2lvblwiOm51bGwsXCJpYmFuXCI6XCIgbnVsbFwifV19In0.h8xXUVaRKPdNsMbdJ5vWaFg3Etz4NTz3ZORJ5VT6AyiGXgibUhyOw1usjayucKUjvQhhDMMDKGmVYqWWjqMUhZvUS-lepAL_hHWfxJoMfWThyDDtAv2aHwvxYhKnK7oVutR_GZEB7OEjJSqI7Ttv9xlDpEutYQz91W6hnToQ5Kq07BSBrOpA5hPdGQ0JiIxWPbW3f68Lnhvq8mAMOGhBbQCx6hGEObPFNX4Yks8TeTdADBV-UgU6FaP-KvZQjjjKeMw2gZCyR9L7AqQuoQypwbKJubzAbduPkjGuxsADbxpacqCx46424uAbHNpkOl5C9Fufwe27o7rFk8J2FCKXKQ

The above header is sent in when the consent is provided as follows:

[
   {
      "accountConsentInfo": {
         "access": {
            "balances": [
               {
                  "iban": "DE40100100103307118608"
               },
               {
                  "iban": "DE02100100109307118603",
                  "currency": "USD"
               },
               {
                  "iban": "DE67100100101306118605"
               }
            ],
            "accounts": [
               {
                  "iban": "FR40100100103307118608"
               }
            ],
            "transactions": [
               {
                  "iban": "DE40100100103307118608"
               },
               {
                  "maskedPan": "123456xxxxxx1234"
               }
            ]
         },
         "combinedServiceIndicator": true,
         "validUntil": "2019-07-10",
         "recurringIndicator": true,
         "frequencyPerDay": 4
      },
      "accountList": [
         {
            "isBalancePermission": null,
            "iban": "DE40100100103307118608"
         },
         {
            "isBalancePermission": null,
            "iban": " DE02100100109307118603"
         },
         {
            "isBalancePermission": null,
            "iban": " DE67100100101306118605"
         },
         {
            "isBalancePermission": null,
            "iban": "FR40100100103307118608"
         },
         {
            "isBalancePermission": null,
            "iban": " DE40100100103307118608"
         },
         {
            "isBalancePermission": null,
            "iban": " null"
         }
      ]
   }
]

A sample decoded JWT Token is given below:

{
   "accountConsentInfo": {
      "accountConsentInfo": {
         "access": {
            "balances": [
               {
                  "iban": "DE40100100103307118608"
               },
               {
                  "iban": "DE02100100109307118603",
                  "currency": "USD"
               },
               {
                  "iban": "DE67100100101306118605"
               }
            ],
            "accounts": [
               {
                  "iban": "FR40100100103307118608"
               }
            ],
            "transactions": [
               {
                  "iban": "DE40100100103307118608"
               },
               {
                  "maskedPan": "123456xxxxxx1234"
               }
            ]
         },
         "combinedServiceIndicator": true,
         "validUntil": "2019-07-10",
         "recurringIndicator": true,
         "frequencyPerDay": 4
      },
      "accountList": [
         {
            "isBalancePermission": null,
            "iban": "DE40100100103307118608"
         },
         {
            "isBalancePermission": null,
            "iban": " DE02100100109307118603"
         },
         {
            "isBalancePermission": null,
            "iban": " DE67100100101306118605"
         },
         {
            "isBalancePermission": null,
            "iban": "FR40100100103307118608"
         },
         {
            "isBalancePermission": null,
            "iban": " DE40100100103307118608"
         },
         {
            "isBalancePermission": null,
            "iban": " null"
         }
      ]
   }
}

psuId

The psuId is a Base64 encoded PSU ID.

psuId: YWRtaW5Ad3NvMi5jb21AY2FyYm9uLnN1cGVy

In the core banking system, the required validations should be performed, and the response is built, according to the requirements of the Open Banking Accounts specification.

Payment Initiation Service flow integration

In WSO2 Open Banking, PISP flow integration with the core banking system is utilised during payment submission requests.

The URL of the API endpoints of the core banking system, which corresponds to the payment submission requests, should be configured in the In sequences of the Payments API. For more information, see Configuring sequence files.

In the Open Banking payments flow, the WSO2 Open Banking solution manages the consent initiation and authorisation. When the TPP makes a payment submission request, it is validated, and upon successful validation, the request is directed to the core banking system. The account ID selected by the PSU, is sent in the form of an encoded header, Account-ID.

In the core banking system, the required validations should be performed. The response should be according to the requirements of the Open Banking Payments specification.

Request Headers

PaymentID (consent id)
PSU-ID (base64 encoded user ID)
Payment-Services
Payment-Product

Request Body

As mentioned in the following sections of the specification:
5.3.1 for single payments, 
11.3 for bulk-payments 
5.3.4.1 for periodic-payments

Response

201 Created

We expect an endpoint from the bank which accepts single payments, bulk payments or recurring payments as mentioned in the Implementation guideline section 5 PaymentInitiationService.

Funds Confirmation Service flow integration

In WSO2 Open Banking, integration of confirmation of funds consent flow with the core banking system is utilised during the confirmation of funds request.

The URL of the API endpoints of the core banking system, which corresponds to the fund's confirmation requests, should be configured in the sequences of the Funds Confirmation API. For more information, see configuring sequence files.

In the Open Banking funds confirmation consent flow, the WSO2 Open Banking solution manages the fund's confirmation consent requests and authorisation. When the TPP makes a fund's confirmation request (POST /funds-confirmations) with the following request, it is validated against the consent details, and directed to the core banking system. The core banking system checks if funds are available in the account and responses with a boolean value to confirm funds:

Transaction Risk Analysis Integration

The Strong Customer Authentication enforces a second-factor authentication for transactions. This can be exempted in certain scenarios as mentioned in the specification. If these rules are met the authenticator will not prompt for a second step. The Transaction Risk Analysis feature is responsible for analyzing and identifying this risk in the transactions.

A possible scenario for you to exempt the strong customer authentication is a situation where the payer and payee are the same people. The bank should provide an API to allow the solution to check whether the payer and payee are the same.

In a merchant scenario, the debtorAccountIdentification and debtorName fields are not included in the request.

Request

POST /PayerPayee
Content-Type : application/Json
Accept: application/json
{
	“authorizedUser” : “john@bank.com” (Mandatory)
	“debtorAccountIdentification” : “DE0210010020033447118603” (Conditional)
	“debtorName” : “John Smith” (Conditional)
	“creditorAccountIdentification” : “DE02100100109307118603” (Mandatory)
	“creditorName” : “C A Tom” (Mandatory)
}

Response

{
	“isPayerAndPayeeSame” : “true” (true or false)
}

Another possible scenario for TRA to analyze and identify risks is if the payee is in the beneficiary list. The bank should provide an API to allow the solution to check whether the payee is in the beneficiary list of the payer.

Request

POST /BeneficiaryList
Content-Type : application/Json
Accept: application/json
{
	
	“authorizedUser” : “john@bank.com” (Mandatory)
	“creditorAccountIdentification”: “DE02100100109307118603” (Mandatory)
	“creditorName” : “C A Tom“ (Mandatory)

}

Response

{
	“isPayeeInBeneficieryList” : “true” (true or false)
}

Payment service user authorisation flow integration

Sharable Accounts API

Retrieve user list for a given account list

Account Information Service flow integration

Payment Initiation Service flow integration

Funds Confirmation Service flow integration

Transaction Risk Analysis Integration