Token Webapp

Token's webapp is available as a standard or customised user interface that bridges TPP service initiation with the bank's SCA and consent mechanisms. As described in Authentication, the Token webapp supports both the Redirect model and the Decoupled model. The SDK can be used to whitelabel/customise the webapp with your logo and colour scheme.

The white label feature, however, first requires permission from Token to create the customisation and have it assigned a customizationId, which you must then include in your TokenRequest to apply the correct customisation.

Obtaining Permission to Customise

To obtain the requisite permission from Token to implement a custom webapp:

  1. Set display_name_first to your business name with a setProfile() call. See Set up a Business Member Profile for details and an example.
  2. Open a support ticket under the Integration category specifying your memberId and request permission to customise the webapp.
  3. Upon receiving approval, call createCustomization(), specifying the parameters identified below in Creating a Custom Webapp. This will return a customizationId.

Be sure to include this customizationId in each subsequent tokenRequest (for access tokens, see Creating an Access Token Request; for transfer tokens, see Creating a Transfer Token Request) or the default Token logo and colours will be applied.

Creating a Custom Webapp

createCustomisation() is a JavaScript API call that specifies a logo asset and color map associated with your appName. Here's the structure:

/**

* Creates a customization.

*

* @param logo - logo

* @param colors - map of ARGB colors #AARRGGBB

* @param consentText - consent text

* @param name - display name

* @param appName - corresponding app name

* @return customization ID

*/

createCustomization(

    logo: BlobPayload, // logo asset

    colors: ?{[string]: string}, // color map in accordance with the table of CSS pairs below

    name: ?string, // name of this customiztion

    appName: ?string // Name of your app

): Promise<string> {

    return Util.callAsync(this.createCustomization, async () => {

        const res = await this._client.createCustomization(

            logo,

            colors,

            name,

            appName);

        return res.data.customizationId;

    });

}

Colour Codes

Colours are specified in 8-digit hex codes (#AARRGGBB). The first two digits (AA) represent the alpha channel. The remainder constitute the RGB components. Create your map of colours — {[string]:string} (example – {[color-primary]:#52FF5F49} — with the following CSS key pairs (adjust the default value according to your desired palette):

Color Map
CSS Colour Attribute Default Value Sample
color-dark #FF1A262C
color-secondary #FF50546C
color-body-text #FF525F7F
color-buttons #FF757F99
color-outlines #FFB8BFCA
color-dividers #FFE9EAF0
color-background #FFFCFCFC
color-light #FFFFFFFF
color-primary #FF05A5F0
color-delete-error #FFEB5757
dolor-disabled-input #FFC4C4C4
color-success-green #FF16AB2B
color-transparent transparent  

Eight-digit hex notation works the same as six-digit notation, in that you provide a six-digit hexadecimal value, prefixed with a hash (#) symbol and the value of the alpha transparency. The first pair of digits (AA) are interpreted as a hexadecimal number (just like the other digits). A value of 00 represents a fully transparent colour, and a value of FF represents a fully opaque colour.

Remember, the values you specify in your custom map will override the default value above for the given key.

Webapp Flow

The Webapp UX comprises the following flows for AISClosedAccount Information Service – supports TPP secure access to customer accounts and data, but only with the bank-verified consent of the customer. and PISClosedPayment Initiation Service – with the consent of the end-user, initiates a payment from a user-held account upon user authentication., respectively (hover to enlarge).

As a TPP you can't change the flow, but you can customise the UI with your own logo and colour scheme.

Webapp Status Messages

Error and status reporting from the webapp are consistent with the codes listed in Payment Status: Values and Meaning for the SDK. However, in the case of the Token Webapp, transfer/transaction status includes both the error code and the bank-transmitted message text ("NSF," Cancelled by user," "Account Closed," etc.). These are included in the callback (see Handling the Token ID/Transfer ID Callback for PISClosedPayment Initiation Service – with the consent of the end-user, initiates a payment from a user-held account upon user authentication., Handling the Token ID Callback for AISClosedAccount Information Service – supports TPP secure access to customer accounts and data, but only with the bank-verified consent of the customer., and Handle the Token ID Callback for CBPIIClosedCard Based Payment Instrument Issuer – a payment services provider that issues card-based payment instruments and allows its customers to pay from bank accounts., respectively).

Browser Button Behaviour During User Redirect

Upon launching Checkout on the merchant web page and confirming account access/payment initiation with the user-selected bank, users will encounter a restriction with respect to using the browser's back button.

If the user clicks the back button during authentication and consent whilst redirected to the bank, the action is trapped and the user is given the option of returning to either the bank or the merchant to either continue with authentication and consent or to restart the process. Until one of these options is selected, however, both the back and forward browser buttons remain disabled.

Support for Query Parameters

Query parameters are a defined set of parameters attached to the end of a URLClosedUniform Resource Locator (aka web address) – specifies a location on a computer network and a mechanism for retrieving it.. They are extensions of the URL that are used to help define specific content or actions based on the data being passed. To append query parameters to the end of a URL, a question mark ('? ') is added, followed by the parameter.

A number of query parameters are supported for webapp redirect. These include parameters that improve the UX by eliminating unnecessary or extraneous user selection, as well as authentication and session parameters using direct references to existing and/or stored TPP requests.

Localisation Parameters

Supported query parameters for localisation currently comprise language (lang) and country (country).

You can specify a particular language by passing its alpha-2 language code (lang=country-code) as a query parameter appended to the redirect URIClosedA Uniform Resource Identifier (URI) is a string of characters that unambiguously identifies a particular resource. To guarantee uniformity, all URIs follow a predefined set of syntax rules, but also maintain extensibility through a separately defined hierarchical naming scheme (e.g. http://).. Here's an example for passing the desired ISO 639-1ClosedCodes for the representation of names of languages—Part 1: Alpha-2 code, is the first part of the ISO 639 series of international standards for language codes. Part 1 covers the registration of two-letter codes. There are 184 two-letter codes registered as of December 2018. The registered codes cover the world's major languages. See https://www.iso.org/iso-639-language-codes.html language code for German (de).

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?lang=de

As pictured next, the user can always override the language preselect in the webapp by clicking the language button in the top-right.

Similarly, to specify a desired country, append an ISO alpha-3 country code to the URI using the country parameter (country=country-code). Austria, for example, would be:

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?country=aut

Authentication and State Parameters

You can also specify a dev key (dk) and/or a state. dk authenticates you to Token-connected banks under a dev-key (typically during sandbox testing), whereas state is the hash of the state with information related to csrfTokenClosedCross-site request forgery, also known as XSRF, Sea Surf or Session Riding – is an attack vector that tricks a web browser into executing an unwanted action in an application to which a user is logged in. CSRFs are typically conducted using malicious social engineering, such as an email or link that tricks the victim into sending a forged request to a server. As the unsuspecting user is authenticated by their application at the time of the attack, it’s impossible to distinguish a legitimate request from a forged one. Token guards against this type of attack by checking each request against the session ID., signatureClosedA qualified electronic signature is an electronic signature that is compliant to EU Regulation No 910/2014 (eIDAS Regulation) for electronic transactions within the internal European market. It verifies the authorship of a declaration in electronic data exchange over long periods of time. Qualified electronic signatures can be considered as digital equivalent to handwritten signatures., etc).

Appending your dk to a webapp redirect will looks something like this:

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?dk=bS0zTFFWQ3BZZjlKaTllN3pmZFlhOHl6MW5ScXhOLTV6S3RYRUFxOjI2OGI0MTYzLTRlZGQtNGU2NC1hMGRlLTQwOWY3MzcyNTVmYw==

Specifying a state in a query parameter, will follow this format:

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?state=bf88b96e972d2c929265cbbfd3872537808006dce061cde12638d4b7258283c6

Concatenation

You can concatenate multiple query parameters for the same URL by separating them with an ampersand ('&'). For example:

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?lang=de&country=aut&
dk=bS0zTFFWQ3BZZjlKaTllN3pmZFlhOHl6MW5ScXhOLTV6S3RYRUFxOjI2OGI0MTYzLTRlZGQtNGU2NC1hMGRlLTQwOWY3MzcyNTVmYw==
&state=bf88b96e972d2c929265cbbfd3872537808006dce061cde12638d4b7258283c6