Building and Storing the CAF Request

CAFClosedConfirmation of Available Funds – A CBPII begins the Confirmation of Funds journey by registering a request to confirm funds of a PSU. The CBPII must then obtain consent from the PSU in order to authorise the request, enabling it to request the information. Once the request is authorised, the CBPII will be able to invoke Confirmation of Funds API to the confirm availability of funds in the PSU account. requests are created with the selected-language variant of the fundsConfirmationRequestBuilder() method. Once the token request is created, you store it, awaiting a corresponding request-id, which is returned by Token in a response payload. In addition to the request-id, the response payload reflects all the information you included in your original request. Equipped with the request-id, you can redeem the token, thereby receiving the requested confirmation of available funds.

Note: The bank will not prompt the user to select a specific account (regardless of whether the user has one or multiple accounts with the bank). The bank will create an access consent only for the account provided in the token request, so you must capture the specified user account before populating the token request.

Even though it's really quite simple and incredibly secure, accuracy remains paramount vis-à-vis making the right calls with the right information at the right time.

So, let's examine the key field definitions for an access token request call.

Tip: Classes, methods and parameters are initially presented in their default Java syntax. Select the corresponding tab — Java, JavaScript or C# in the navigation bar of the first code example in the sequence — to display the correct syntax and field names for the SDK language chosen.

Here's the basic structure of the request.

// Entry point

private static final Member cbpiiMember = initializeMember(tokenClient);

. . .

// Create a token request to be stored

TokenRequest tokenRequest = TokenRequest.fundsConfirmationRequestBuilder(

       "iron", // set the bankId











        .setCsrfToken(csrfToken) // validates the session ID

        // use keys in bank authorization metadata from getBanks() response




// Store the request

String request-id = cbpiiMember.storeTokenRequestBlocking(tokenRequest);

The key fields comprising a CAF access token request are defined in the following table.

Fields in a CAF Request
Field Description Required/ Optional
accountId Account number being queried; set using the AccountIdentifier object, which allows four types of account identifiers:

Although setting source with the BankAccount object has been deprecated, it is still supported

authorizationMetadata Needed to capture additional information from the user for initial authorization by the bank, thereby allowing the user to proceed with providing consent for the initiation request. Maps the key-value pairs from the getBanks() response, where key is the name of the field and value is the value of the field. Required
bankId Must be specified for CAF requests; indicates you wish to bypass the Token bank selection UI and use your own bank selection UI for the request. See Using the getbanks Method Required
callBackState TPP-specified string that persists state between request and callback Optional, but recommended
customizationId Identifier for customizing the UI of the Token web app (see Customising the Token Webapp for details) Optional
description Description of the payment with the following qualifiers:
  • description in a subsequent call must match description in originating request
  • description omitted in originating request must also be omitted in subsequent calls
  • description omitted in subsequent call will be replaced with refId

This description field maps to description in the bank's consentRequest presented to the user.

Warning: If description in a subsequent token request for lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception will be thrown.

grantee The "To" TPP member placing the access request, which will receive the information upon successful token redemption Required
grantor User Alias (DOMAIN orEMAIL) of the user member granting access to the specified bank account. To review the methods for finding an alias see Fetching an Alias. Required
receiptRequested Boolean; requests a receipt be sent to the grantor member's default email address Optional
redirectUrl Specifies the callback URL where your server will initiate token redemption Required

Reference identifier for the token; not to be confused with requestId. RefId maps to tppRefId in the bank's consentRequest. It is needed to match/verify the originating token request with the bank's consent request.

Warning: A description mismatch between the originating token request and subsequent token lookups/changes/updates (retrieve, redeem, or cancel) will throw an exception.

resourceType Specifies the type of information for which access permission is requested; in this case,  FUNDS_CONFIRMATIONS – confirmation of available funds in the specified account Required
token_expiration Sets the expiration date and time for the token request (default is 20 minutes); override of default value is not supported by all banks Optional
traceID TPP-provided unique value captured by Token and sent across to the bank to be stored with the request throughout its lifecycle as an audit-trail aid. Optional

After storing the transfer token request, you're ready to construct the redirect URL for authorisation so the customer can authenticate, provide consent, and authorise account information access for funds confirmation as previously outlined in the CAF communication workflow.

Caution: A PANClosedPrimary Account Number – refers to a 14-, 15-, 16-, or even up to 19-digit number generated as a unique identifier designated for a primary account; also called payment card number and permanent card number. is disallowed in the token request payload within the refId and description fields. In accordance with the PA-DSSClosedPayment Application Data Security Standard – Council-managed program formerly under the supervision of the Visa Inc. program known as the Payment Application Best Practices (PABP). The goal of PA-DSS is to help software vendors and others develop secure payment applications that do not store prohibited data, such as full magnetic stripe, CVV2 or PIN data, and ensure their payment applications support compliance with the PCI DSS. Payment applications that are sold, distributed or licensed to third parties are subject to the PA-DSS requirements. In-house payment applications developed by merchants or service providers that are not sold to a third party are not subject to the PA-DSS requirements, but must still be secured in accordance with the PCI DSS. security standard, RegexClosedAPI to define a pattern for searching or manipulating strings. is used for pattern matching of numeric strings that intentionally or inadvertently reveal or resemble a PAN in the refId or description of a token request. Potential PAN patterns found will throw an exception.

Tip: When integrating the Token SDK with a mobile app, you can initiate the token request in WebViewClosedA browser engine that you can insert like an iframe into your native app and programmatically tell it what web content to load. so that the redirect is also in the form of an HTTP 302ClosedAn HTTP response with this status code will additionally provide a URL in the header field Location. This is an invitation to the user agent (i.e., a web browser) to make a second, otherwise identical, request to the new URL specified in the location field. The end result is a redirection to the new URL.. However, in terms of activity layout, WebView lacks many features found in a fully developed web browser.

Nevertheless, WebView provides increased control over the UI and advanced configuration options that allow you to embed web pages in a specially-designed environment for your app, but you will forfeit an array of features supported by Chrome, Firefox, and other COTSClosedCommercial off-the-shelf – a product designed to be easily installed and to interoperate with existing system components. browsers.