Confirmation of Funds API for UK

This documentation explains the flow of the Confirmation of Funds API by OBIE. introduced in WSO2 Open Banking The Confirmation of Funds API allows users to create a funds confirmation consent request, and manage the funds confirmation consents by checking and revoking the status. The Card-Based Payment Instrument Issuer (CBPII) must request to create the resource to create a funds confirmation consent request.

Endpoints for the API allows the Card-Based Payment Instrument Issuer (CBPII) 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. It consists of an expiration date for the funds consent granted by the PSU to the CBPII.
• 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 Confirmation of Funds API. It is assumed that the CBPII 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 CBPII 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 CBPII requests the PSU to provide consent.
5. PSU approves the consent - The ASPSP carries out the agreement of consent in a decoupled or a redirect flow. 
   1. Currently, WSO2 Open Banking supports the redirect flow. Thereby, the CBPII redirects the PSU to the ASPSP. In the redirect flow:
      1. The ASPSP can co-relate the funds confirmation consent resource created by the CBPII using the ConsentID generated in step 3.
      2. The ASPSP authenticates the PSU.
      3. The PSU grants explicit consent to the ASPSP to respond to the confirmation of funds request.
      4. The ASPSP updates the funds-confirmation-consent resource internally to authorise the resource.
      5. Once the consent is authorised, the PSU is redirected back to the CBPII.
   2. In a decoupled flow, the PSU must authorise the consent from an authentication device. This request is made by the ASPSP to the PSU.
      1. The decoupled flow is initiated by the CBPII calling a back-channel authorisation request.
      2. The request has a hint that indicates that the PSU is paired with a to-be-authorised consent.
      3. The ASPSP authenticates the PSU.
      4. The PSU grants explicit consent to the ASPSP to respond to the confirmation of funds request.
      5. The ASPSP updates the funds-confirmation-consent resource internally to authorize the resource.
      6. Once the consent is authorised, the ASPSP can make a callback to the PISP to provide an access token.
6. Confirm funds - A card payment is directly or indirectly initiated by the PSU.

The CBPII 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.
  • ConsentId - an ID that relates the request to a funds-confirmation-consent, and specific account with the ASPSP. This ID must match the intent identifier.
• Get Funds Confirmation Consent Status - The CBPII checks the status of  funds-confirmation-consent resource with the consentId. This step is carried out by a GET request to the funds-confirmation-consents endpoint with the client credentials grant.

Sequence diagram

The flow consists of 3 components:

1. Funds-confirmation-consent initiation  

Generating application access token

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

Initiating a funds confirmation consent

• The CBPII communicates with the ASPSP using the Confirmation of Funds API available in the WSO2 Open Banking solution.
• CBPII 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 API Management module in the WSO2 Open Banking solution. 
• The Request Schema Validation Handler inside the API Management module then validates 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 IAM module in the solution where a unique UUID for the consent (Consent Id) is generated.

2. Funds-confirmation-consent authorisation

• CBPII sends the authorisation request and this will be captured from the Authorisation endpoint in the API Management module.
• The request details are then passed to the IAM module. 
• The Request Object Validator in WSO2 OB IAM - Identity Framework validates the request object and its claims, and share the validation results.
• These details are stored in cache against a session data key. 
• The session data key is shared with the CBPII in an authentication endpoint URL. 
• The CBPII 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 Consent Id. This newly added scope provides necessary permissions to retrieve account information.
• Then the IAM module generates the authorization code and shares it with the CBPII through the redirect URL.

3. Funds confirmation 

Generate user access token

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

Confirm Funds

• The CBPII 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 CBPII would like to confirm funds are available in the specific payment account.
• The APIM Gateway module then validates the CBPII’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 Consent Id by calling Consent Validation module and checks if the access token associated with the request contains a scope with the Consent Id.
• This handler compares and validates the x-fapi-financial-id header in the incoming request against the one configured in the solution (open-banking.xml file).
• Then the request is forwarded to the IAM module for consent validation. The Consent Validation module inside IAM validates the following:
• Status of the consent is Authorised.
• Consent is valid/not expired.
• Permissions granted for the respective Consent Id 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 Consent Id in the request against the databases. 
• After successful validations, the Consent Validation module sends details related to funds-confirmation-consent in a header as mentioned in Integrating with the Core Banking System for UK - Confirmation of Funds API.
• The validation results are then shared with the API Management 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.  

Endpoints

Once you deploy the Confitmation of Funds API, you can access consent and funds confirmation information via following API endpoints: