Confirming Funds

A PSU is requested to confirm on the funds that are available to CBPII. An ASPSP responds to the funds-confirmation endpoint with a boolean value. The Funds confirmation endpoint is used as following:

Endpoints

Resource	HTTP Operation	Endpoint	Mandatory/Optional	Scope	Grant Type	Message Signing	Idempotency Key	Request Object	Response Object
funds-confirmation	POST	POST /funds-confirmations	Mandatory	fundsconfirmations	Authorization Code	No	No	OBFundsConfirmation1	OBFundsConfirmationResponse1

Generate an application access token

When invoking APIs in the CBPII flow, application access tokens must be generated using the client credential grant type.

Generate the client assertion by signing the following JSON payload using the supported algorithms.

{
  "alg": "<<This will be the algorithm used for signing>>",
  "kid": "<<This will be the certificate fingerprint>>",
  "typ": "JWT"
}

{
  "iss": "<<This is the issue of the token, e.g., client ID of your application>>",
  "sub": "<<This is the subject identifier of the issuer, e.g., client ID of your application>>",
  "exp": <<This is epoch time of the token expiration date/time>>,
  "iat": <<This is epoch time of the token issuance date/time>>,
  "jti": "<<This is an incremental unique value>>",
  "aud": "<<This is the audience that the ID token is intended for, e.g., https://<<AM_HOST>>:8243/token>>"
}
<signature>

Run the following cURL command in a command prompt to generate the access token. Make sure you update the placeholders with the relevant values.

curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" -k -d "grant_type=client_credentials&scope=fundsconfirmations&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<pass the signed key generated in the above>>&redirect_uri=<<The callback URL of your application>>" https://<<AM_HOST>>:8243/token

You can use the same cURL command to re-generate the access token.

Invoke the confirmation of funds API

In this step, the TPP passes the customer-provided consents to the bank. The bank validates the request and stores the user consents.

Navigate back to the API Store while logged in as a TPP user.
Click APIs.
Select the confirmation of funds API.

Click the POST /funds-confirmation-consents resource.

Use the following as the body:

The ExpirationDateTime should be a future date and time.

{
  "Data": {
    "DebtorAccount": {
      "SchemeName": "<<Name of the identification scheme, in a coded form as published in an external list>>",
      "Identification": "<<Identification assigned by an institution to identify an account>>",
      "SecondaryIdentification": "<<Secondary identification of the account, as assigned by the account servicing institution>>"
    },
    "ExpirationDateTime": "<<Specified date and time the funds confirmation authorisation will expire>>"
  }
}

Enter a unique ID that identifies the ASPSP to the x-fapi-financial-id field.
In the Authorization field, enter the application access token you created in the Generate application access token section. Use the bearer: access token format.
Click Try it out! The API response bears the ConsentId.

Invoke/authorize API

A bank customer is redirected by the TPP to authenticate and approve/deny an application that has the consent on behalf of the PSU.

Generate the request object by signing the following JSON payload using the supported algorithms while signed in as a TPP user.

{
  "alg": "<<This will be the algorithm used for signing>>",
  "kid": "<<This will be the certificate fingerprint>>",
  "typ": "JWT"
}

Body
{
	"aud": "<<This is the audience that the ID token is intended for, e.g., https://<<AM_HOST>>:8243/token>>",	
	"iss": "<<This is the issue of the token, e.g., client ID of your application>>",
	"response_type": "<<This can be code or code id_token>>", 
	"client_id": "<<This is the client ID of your application>>",
	"redirect_uri": "<<This is the callback URL we set during application access token generation. Ref: Generate Application Access Token section>",
	"scope": "fundsconfirmations openid",
	"nonce": "<<This is a value used to prevent replay attacks>>",
	"max_age": 86400,
	"claims": {
    	"userinfo": {
        	"openbanking_intent_id": {
            	"value": "<<This is the ConsentId retrieved in Invoke the ConfirmationOfFundsAPI API section>>",
            	"essential": true
        	}
    	},
    	"id_token": {
        	"openbanking_intent_id": {
            	"value": "<<This is the ConsentId retrieved in Invoke the ConfirmationOfFundsAPI API API section>>",
            	"essential": true
        	},
        	"acr": {
            	"essential": true,
            	"values": [
                	"urn:openbanking:psd2:sca",
                	"urn:openbanking:psd2:ca"
            	]
        	}
    	}
	}
}
<signature>

For the response type, use the values based on its purpose

code: Retrieves the authorize code
code id_token: Retrieves the authorize token and the ID token

Run the following in a browser to prompt the invocake/authorize API. Make sure you update the placeholders with the relevant values.

https://<<AM_HOST>>:8243/authorize/?response_type=code%20id_token&client_id=<<the client-id of your application>>&scope=fundsconfirmations openid&redirect_uri=<<The Callback URL of your application>>&prompt=login&request=<<The request object generated in the step above>>

Once you pass this call, you are directed to a login page. Log in with the credentials of a user with a subscriber role.
If a secondary factor is required (e.g., SMSOTP), provide the relevant values.
Upon successful authentication, the user is redirected to the consent management page.
Upon providing consent, an authorization code is generated.

Generate user access token

This step involves generating an access token using the authorization code generated in the Invoke/authorize API section above. It is used to call the POST /funds-confirmations endpoint.

Run the following cURL command in a command prompt to generate the access token and a refresh token while signed in as a TPP user.

curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=<<Authorization code we generated in the Invoke the /authorize API section>>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<Client assertion generated in step 2 of the Generate Application Access Token section>>&redirect_uri=<<The Callback URL of your application>>" https://<<AM_HOST>:8243/token

You can renew the access token using the refresh token. To renew an access token, see Renew the access token.

Invoke confirmation of funds API's

When TPP actually needs to invoke the confirmation of funds (COF) API, the bank validates if the TPP sends the COF API request based on the approved consents by the PSU.

Use the user access token generated in the step above to invoke the APIs (v3.1.0) as shown below:

Confirmation Of Funds API

curl -X POST --header 'Accept: application/json' --header 'x-fapi-financial-id: open-bank' --header 'Content-Type: application/json'  --header 'Authorization: Bearer <<access token>>' --data '{"Data": {"ConsentId":" <<consent id>>", "Reference": "<<refference>>", "InstructedAmount": { "Amount": "<<amount>>", "Currency": "<<currency>>" }}}' 'https://<<AM_HOST>>:8243/open-banking/v3.0/cbpii/v3.0.0/funds-confirmations' -k

Renew the access token

This step involves regenerating the access token that was generated using the authorization code in the Generate Application Access Token section above.

Run the following cURL command to call the refresh_token endpoint and regenerate a new access token while signed in as a TPP user.

curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=refresh_token&refresh_token=<<refresh token token>>&scope=fundsconfirmations openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<Client assertion generated in step 2 of the Generate User Access Token section>>&redirect_uri=<<The Callback URL of your application>>" https://<<AM_HOST>>:8243/token/

Requesting to create `funds confirmation`

Funds Confirmation Endpoint

POST /funds-confirmations

In order to verify the PSU's consent for a transaction, CBPII first requests to create a funds-confirmation resource with the relevant ASPSP where the PSU's accounts details are stored. This is the step 5 of the Basic flow.

The ASPSP creates the funds-confirmation resource and responds with the unique fundsConfirmationId in order to refer the resource.
The ASPSP flags confirming if the funds are available in the payment account.
The step is carried out in a POST request to the funds-confirmation endpoint with an authorization code grant. The authorization code grant generates a token that the CBPII must specify in the request payload.
This CBPII must use a currency of the account.
The CBPII requests for the funds confirmation with the ConsentId. The request includes these data fields:
- ConsentId
- Reference
- Amount
- Currency

Amount and Currency fields are checked in the payment account that the ASPSP has given consent to confirm on available amounts by the PSU. The Currency must be the currency of the account.

Post Funds Confirmation Request

POST /funds-confirmations HTTP/1.1Content-Type: application/json
Authorization: Bearer 1t1satruthun1v3rs4lly
Accept: application/json; charset=utf-8
x-fapi-financial-id: I4mth3R3-4p3r-411t-hing-5withh33dfu1
x-fapi-interaction-id: hook5i13-ntIg-4th3-rP41-3ro535touch3
 
{
  "Data": {
    "ConsentId": "88379",
    "Reference": "Purchase01",
    "InstructedAmount": {
       "Amount": "20.00",
       "Currency": "GBP"
    }
  }
}

Post Funds Confirmation Response

HTTP/1.1 201 CreatedContent-Type: application/json
x-fapi-interaction-id: hook5i13-ntIg-4th3-rP41-3ro535touch3
 
{
  "Data": {
    "FundsConfirmationId": "123456",
    "ConsentId": "88379",
    "CreationDateTime": "2017-05-02T00:00:00+00:00",
    "FundsAvailable": true,
    "Reference": "Purchase01",
    "InstructedAmount": {
       "Amount": "20.00",
       "Currency": "GBP"
    }
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v3.1/cbpii/funds-confirmations/123456"
  },
  "Meta": {}
}

Example with a USD payment account.

This is a funds confirmation checked on a USD payment account.

A funds confirmation check can be made in a Currency that is in the currency of the payment account.