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

Accounts API

Account Information Retrieval

In WSO2 Open Banking, integration of accounts flow 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 consent initiation and authorisation. 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, Account-Request-Information.

This header is a signed JWT, which needs to be decoded by the core banking system. A sample decoded JSON is given below:

{
  "accountRequestIds": [
    {
      "accountId": [
        "30080012343456"
      ],
      "transactionFromDateTime": "2020-07-13T18:47:22.521+05:30",
      "transactionToDateTime": "2020-07-16T18:47:22.522+05:30",
      "permissions": [
        "ReadAccountsBasic",
        "ReadAccountsDetail",
        "ReadBalances",
        "ReadBeneficiariesBasic",
        "ReadBeneficiariesDetail",
        "ReadDirectDebits",
        "ReadProducts",
        "ReadStandingOrdersBasic",
        "ReadStandingOrdersDetail",
        "ReadTransactionsBasic",
        "ReadTransactionsCredits",
        "ReadTransactionsDebits",
        "ReadTransactionsDetail",
        "ReadStatementsBasic",
        "ReadStatementsDetail",
        "ReadOffers",
        "ReadParty",
        "ReadPartyPSU",
        "ReadScheduledPaymentsBasic",
        "ReadScheduledPaymentsDetail",
        "ReadPAN"
      ]
    }
  ]
}

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.

Payments API

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.

Payments Submission

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

Single Authorisation

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 Payment Service User (PSU), is sent in the form of an encoded header, Account-ID.

Multiple- Authorisation

An account can have only one owner or more than one owner. For multiple owners, each and every owner has to authorise the account (multiple-authorisation) while it is single-authorisation for one owner. Let's look at a multiple authorisation scenario in the Payments API.

When the TPP makes a multiply-authorised payment submission request, it is validated, and upon successful validation, the request is directed to the core banking system. The payment submission information is sent in the form of an encoded header, Multiple-Authorization-Information.

This header is a signed JWT, which needs to be decoded by the core banking system. A sample decoded JSON is given below:

{  
"Status": {    
	"status": "AwaitingFurtherAuthorisation"  
	},  
"NumberReceived": 1,  
"LastUpdateDateTime": 1594999807000,  
"ExpirationDateTime": 1595258987000,  
"NumberRequired": 2
}

When it is multiply-authorised, the bank needs to check if each owner has authorised the request. The bank retrieves the status of the authorisation using the GET/Status call.

Funds Confirmation

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

In the Open Banking payments flow, the WSO2 Open Banking solution manages the consent initiation and authorisation. When the TPP makes a funds confirmation request for domestic payments, international payments, and international-scheduled payments; it is validated. Upon successful validation, the request is directed to the core banking system. The funds-confirmation-related information is directed to the core banking system in the form of a header, Funds-Confirmation-Information

This header is a signed JWT, which needs to be decoded by the core banking system. A sample decoded JSON is given below:

{
  "Amount": "30.80",
  "Currency": "GBP",
  "Identification": "30080012343456"
}
Idempotency key

Idempotency key is used as an identifier to check a replication of an action. The use cases of the idempotency key are:

  • Payment initiation request

     Click here see how idempotency key is used in the payment initiation request...

    WSO2 Open Banking validates the idempotency key that is sent in the payment initiation request as x-idempotency-key. A payment initiation request can be replicated in situations like security vulnerabilities and network failures. In that case, the x-idempotency-key secures the payment initiation flow as WSO2 Open Banking checks the existing idempotency keys and generates responses accordingly. 

    1. A payment initiation request is made by the TPP with an idempotency key. 
      For each payment initiation request with unique idempotency keys, the WSO2 Open Banking solution responses exclusively.
    2. There can be two scenarios where the TPP can replicate the idempotency key as below:
      1. The TPP sends the same payment initiation request with the same idempotency key - The WSO2 Open Banking solution sends the same response for the consent ID (HTTP 201)  that was initiated for the payment in step 1.

      2. The TPP sends a different payment initiation request with the same idempotency key - The WSO2 Open Banking solution sends an error (HTTP 401) that was initiated for the payment in step 1 as the idempotency key cannot be duplicated for another payment initiation request.

    See the diagram below to understand how the x-idempotency-key in the payment initiation API resource is validated by WSO2 Open Banking.

  • Payment submission request

     Click here to see how idempotency key is used in the payment submission request...

    In Open Banking, the ASPSP is the entity that saves the idempotency key and responds to payment submission requests. Therefore, the ASPSP must consider the following scenarios and respond accordingly:

    • Payment submission requests with duplicated idempotency keys
    • Payment submission requests with duplicated consent IDs 
In the core banking system, the required validations should be performed, and the response is built, according to the requirements of the Open Banking Payments specification.

Confirmation of Funds API

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 In 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), it is validated against the consent details, and directed to the core banking system. Similar to the payment's submission request, the account ID of the consent is sent in the request as an encoded header, accountId.

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

Accounts Retrieval Endpoints

In some banks, some PSUs may have a certain number of accounts, but not all accounts have the ability to be shared externally or to make a payment online. In a bank, the shareable account list and the payable account list can either be the same or different.

In the default WSO2 Open Banking solution, at least two APIs are expected to return shareable and payable accounts when passing the user_id, and the given JSON response must be returned. Then it automatically loads the accounts list in the consent page. 

Payable Accounts API

The back end endpoint for the Payable Accounts API is used to get the payable accounts of the user during the authentication flow. If Third Party Application (TPP) has not provided any debtor account in payment initiation request, PSU is able to select one of these payable accounts when providing the consent to the payment. If the TPP has sent the debtor account in the initiation request, this API is used to validate the provided account against actual payable accounts. consentId and userId (PSU ID) requires to be sent in the URL as query parameters when calling this API.

The back end endpoint for payable accounts retrieval can be configured in the open-banking.xml file as below. By default, mock backend deployed in the API Manager is configured.


<PayableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9763/open-banking/services/bankaccounts/bankaccountservice/payable-accounts</PayableAccountsRetriveEndpoint>

Required parameters can be passed as query parameters to those endpoints. An example of configuring the endpoint to retrieve payable accounts:

<PayableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9443/as400/payable-accounts/{userId}</PayableAccountsRetriveEndpoint>
{
 "data": [{
	"account_id": "30080098971337",
	"display_name": "account 1",
	"authorizationMethod": "single",
}
	{
		"account_id": "30080098971337",
		"display_name": "30080098971337",
		"authorizationMethod": "multiple",
		"authorizationUsers": [{
		"customer_id": "123",
		"user_id": "[email protected]@carbon.super"
    },
    	{
			"customer_id": "456",
			"user_id": "[email protected]@carbon.super"
    	}
   ]
  }
 ]
}

Shareable Accounts API

Shareable Accounts API is used for two purposes as follows.

  1. Validate the debtor account if the PISP sends it in the initiation request

  2. Populate the payment accounts on the consent page if the initiation request does not contain a debtor account.

consentId and userId (PSU ID) requires to be sent in the URL as query parameters when calling this API.

The backend endpoint for shareable accounts retrieval can be configured in open-banking.xml file, by default this is connected to the mock back end in the API Manager server.

<SharableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9763/open-banking/services/bankaccounts/bankaccountservice/sharable-accounts</SharableAccountsRetriveEndpoint>

Required parameters can be passed as query parameters to those endpoints. An example of configuring the endpoint to retrieve sharable accounts: 

<SharableAccountsRetriveEndpoint>http://<WSO2_OB_APIM_HOST>:9443/as400/sharable-accounts/{userId}</SharableAccountsRetriveEndpoint>

  • No labels