Funds Confirmation Service for Berlin

This documentation explains the flow of the Funds Confirmation Service. In WSO2 Open Banking, the Funds Confirmation Service allows users to create a funds confirmation consent request, and manage the funds confirmation consents by checking and revoking the status. The Payment Instrument Issuing Service Provider (PIISP) must request to create the resource to create a funds confirmation consent request.

Endpoints for the API allows the PIISP to:

• Request fund confirmation by creating a funds confirmation consent resource with an Account Servicing Payment Service Provider (ASPSP). There must be an agreement between the Customer (PSU) and ASPSP. 
• Confirm the funds that are available from time to time. Funds can only be confirmed against the currency of the account.

The sections below describe the following:

Basic flow

The diagram below shows the request flow of the Funds Confirmation Service. It is assumed that the PIISP has issued a PSU a card and that the PSU would like to use the card adhering to PSD2. 

1. Initiates a card payment - The PSU initiates a card payment. 
2. Create funds confirmation consent - The PIISP requests to create a funds-confirmation-consent resource by connecting to the ASPSP that supports the PSU's funds.
3. Provide the consent resource -  The ConsentId (Consent identifier) is generated by the ASPSP to respond to the resource.
4. Request to agree with the funds confirmation consent - The PIISP requests the PSU to provide consent.
5. PSU approves the consent - The PSU approves/denies the consent for the TPP to initiate the payment.
6. Confirm funds - A card payment is directly or indirectly initiated by the PSU.

The PIISP then requests to create a funds-confirmation resource by connecting to the ASPSP where the PSU's account is supported. 

• This indicates to the ASPSP that the PSU would confirm that the payments are available for the specific payment account.
• The ASPSP responds with a boolean (YES/NO) to the funds-confirmation-consent resource.
• The step is carried out in a POST request to the funds-confirmation endpoint with an authorisation code grant.
• The payload will include these fields, which describe the data that the PSU has consented with the CBPII:
  • Amount - the amount to be confirmed available.
  • Card Number - The card number for which you are checking if funds are available.
  • Account - The bank account associated with the card.
  • Currency - The currency type to initiate payments.

Sequence diagram

The flow consists of 3 components:

1. Funds confirmation consent initiation  

Generate application access token

• The PIISP requests the ASPSP for an application access token. This call targets the Gateway in WSO2 Open Banking API Management (WSO2 OB APIM) module.
• There, the APIM Gateway validates the PIISP’s certificates using Mutual TLS authentication and forward the request to the WSO2 Open Banking Identity and Access Management (WSO2 OB IAM) module.
• The OAuth2 Framework in the WSO2 OB IAM module performs further validation and provides the PIISP with an application access token in the Client Credentials grant type.

Initiate funds confirmation consent

• The PIISP communicates with the ASPSP using the Confirmation of Funds API available in the WSO2 Open Banking solution.
• PIISP sends a funds confirmation initiation request to ASPSP with the purpose of creating a funds-confirmation-consent resource for a given payment account for a particular PSU. This request contains the application access token generated in the previous step. 
• This request targets the WSO2 APIM module in the WSO2 Open Banking solution. 
• The Request Schema Validation Handler and Signature Validation Handler inside the WSO2 APIM module then validate the request against the respective( Confirmation of Funds) Swagger file. For example, mandatory header, payload fields, pattern matching for fields.
• The back end call of the initiation request is redirected to the WSO2 OB IAM module in the solution where a unique UUID for the consent (ConsentId) is generated.

2. Funds-confirmation-consent authorisation

Consent authorisation includes the following: 

• ASPSP authenticates the PSU.
• ASPSP sends the consent to the PSU to get it authorised. The PSU may accept/reject the consent.

Once these steps are complete, the consent is considered to have been authorised by the PSU.

• PIISP sends the authorisation request and this will be captured from the Authorisation endpoint in the WSO2 OB APIM module.
• The request details are then passed to the WSO2 OB IAM module.  
• The PIISP needs to redirect the PSU to this URL.
• The PSU uses the authentication URL to log in to the authentication endpoint.
• Based on the authenticators that the ASPSP has configured (basic authentication or two-factor authentication), the PSU needs to provide the relevant values. Upon successful authentication, the PSU is redirected to the consent management page. 
• There, the PSU authorises the consent. The consent management module updates the consent details and persists them in a database.
• The Authentication endpoint invokes the Response Type Handler inside the IAM module and it stores a custom scope against the access token with the ConsentId. This newly added scope provides necessary permissions to retrieve account information.
• Then the WSO2 OB IAM module generates the authorization code and share it with the PIISP through the redirect URL.

3. Funds confirmation 

Generating user access token

• The PIISP requests for a user access token using the generated authorisation code. This call targets the Gateway in WSO2 OB APIM module.
• There, the APIM Gateway validates the PIISP’s certificates using Mutual TLS authentication and forward the request to the WSO2 OB IAM module.
• The OAuth2 Framework in the WSO2 OB IAM module performs further validation and provides the PIISP with the user access token.

Confirm Funds

• The PIISP makes another API call to the published (Confirmation of Funds) API in the WSO2 API store to confirm funds using the access token obtained from the step above. 
• This informs the ASPSP that the PIISP would like to confirm funds are available in the specific payment account.
• The APIM Gateway module then validates the PIISP’s certificates and the access token. The Consent Enforcement Handler in the API Management module validates the incoming request against the saved consent details. The Consent Enforcement Handler performs the following:
• When a retrieval request is made, this handler validates the ConsentId by calling consent validation module and checks if the access token associated with the request contains a scope with the ConsentId.
• Then the request is forwarded to the IAM module for consent validation. The consent validation module inside WSO2 OB IAM validates the following:
• Status of the consent is Authorised.
• Consent is valid/not expired.
• Permissions granted for the respective ConsentId and if they match with the accessing API resource. 
• Published API version against the requested API version, as the specification allows cross-version accessing.
• The consent management module validates the ConsentId in the request against the databases. 
• The validation results are then shared with the WSO2 OB APIM module. Then the bank backend is queried to retrieve whether the requested funds are available in the payment account. The FundsAvailable flag in the response is a boolean value that indicates the availability of funds.