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 TokenRequests 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 AIS and PIS, 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," Canceled 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).