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/.
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.0 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.0 APIs, authorisation service was set in place that facilitates multi-level SCA (multiple authorizers on one consent) and authorisation cancellations. WSO2 Open Banking 1.4.0 also introduces 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.
RequestGET /shareable/{userId} Content-Type: application/json Accept: application/json
Response{ "accounts": [ { "iban": "DE12345678901234567890", "bban": "BARC12345612345678", "pan": "5409050000000000" } ] }
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.Retrieve user list for a given account list
POST /accounts/users/
Accept: application/json
Content-Type: application/json
{
"accounts": [
{
"iban": "DE12345678901234567890",
"bban": "BARC12345612345678",
"pan": "5409050000000000"
}
]
}
{
"accounts": [
{
"identification": {
"iban": "DE12345678901234567890",
"bban": "BARC12345612345678",
"pan": "5409050000000000"
},
"users": [
{
"customerIdentification": "JEAN123",
"userIdentification": "jean.luc.picard@enteprise.org"
}
]
}
]
}
AISP 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.
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.
PISP 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.
PaymentID (consent id) PSU-ID (base64 encoded user ID) Payment-Services Payment-Product
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
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.
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
anddebtorName
fields are not included in the request.RequestPOST /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
RequestPOST /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) }