Get started

Get started using Token.io's platform to create merchants and initiate payments with our LaunchPad. Contact our Sales team for more information.

Token.io basics

Familiarize yourself with fundamental concepts regarding Token.io's Open Banking solution and its services architecture.

Smart tokens

In Open Banking, tokens replace identifying information about the user and the user's bank account information or the user and a payment request with what appears to be a random string of characters and numbers. Nobody knows what the token actually means or the information it contains except the bank. Tokens are made even more inscrutable using encrypted communication between the TPP, Token.io and the bank.

Smart tokens are at the heart of Token.io's Open Banking solution. Each token comprises three major components: asset, rules, and state. The asset is what the token represents (i.e., what it is being exchanged for). The rules govern how it can be used, when it can be used, by whom and with whom. Its state reflects whether or not it is active/unused, canceled, or redeemed. What this all boils down to is that a token can be used only once and only by the party to whom it was originally issued and strictly for the purpose for which it was issued, providing inherent security in each request-reply exchange.

For PSD2, smart tokens come in two kinds: transfer tokens and access tokens. Transfer tokens authorize payment or the transfer of assets or funds from a payer to a designated payee. They function as programmable money. Access tokens authorize user-approved access to a member's bank account information. The type and level of access granted by the bank depends on the conditions set for the access token — “who,” “what,” “how,” and "when" that data can be accessed and "by whom".

A typical transfer token use case comes to bear when a business (the payee) requests a member (the payer) to authorize a smart token to pay for an online purchase: “Allow Business XYZ to initiate a payment from my bank account to pay €224 for order 79262212.“

A typical access token use case is when a member (the grantor) authorizes a service (the grantee) to access and aggregate their bank account information.

A token is created upon successful user authentication with the bank. It contains all the details specified in the request.

Tokens are redeemed to execute a payment (single, future-dated, bulk transfers) or a series of payments (recurring, based on a standing order), or to access account information. For transactions, you will receive a transfer ID in a callback from Token.io after successfully initiating a payment on your user's behalf. This means the transfer token has been redeemed and no further action is required. For account information, the access token ID you receive in response to an AIS request is redeemed in accordance with the consent granted by the user for account balance(s) and/or transaction history.

An unused token can be retrieved to check its status based on matching properties. Unredeemed tokens can be canceled at any time.

Cryptography – keys and key management

Cryptography is an ancient mathematical science originally used for military communications designed to conceal the contents of a messages should they fall into enemy hands. Recent developments in cryptography have added additional uses, including mechanisms for authenticating users on a network, ensuring the integrity of transmitted information, and preventing users from repudiating (rejecting ownership of) their transmitted messages.

Data that can be read and understood without any special measures is called plaintext or cleartext. The method of disguising plaintext in such a way as to hide its meaning and substance is called encryption. Encrypting plaintext results in unreadable gibberish called ciphertext. You use encryption to ensure that information is hidden from anyone for whom it is not intended, even those who can see the encrypted data. The process of reverting ciphertext to its original plaintext is called decryption.

With end-to-end encryption, one end of a communication encrypts the contents of a message on its local machine or device. That data is then transmitted as ciphertext to the intended recipient on the other end, who alone can decrypt and read it using the appropriate secret "keys."

Data can be encrypted in transit and/or at rest. Information sent from a browser to a website and vice versa is data "in transit." Information stored on a computer or on a server is data "at rest."

A key is a value that works with a cryptographic algorithm to produce a specific ciphertext. Measured in bits, keys are basically super big numbers. The bigger the key, the more secure the ciphertext.

Public key cryptography ()is an asymmetric scheme that uses a pair of keys for encryption — a public key, which encrypts data, and a corresponding private key, for decryption. Anyone with a copy of the public key can encrypt information that only someone with the private key can read.

A major benefit of public key cryptography is that it provides a method for employing digital signatures. Digital signatures enable the recipient of information to verify the authenticity of the information’s origin, and also verify that the information is intact. In this way, public key digital signatures provide authentication and data integrity. A digital signature also provides non-repudiation, which means that it prevents the sender from claiming that he or she did not actually send the information.

A digital signature serves the same purpose as a handwritten signature and is nearly impossible to counterfeit. Moreover, it not only attests to the content of the information, it certifies the identity of the signer.

It should go without saying that key storage must be carefully and securely managed. Encryption key management means administering the full lifecycle of cryptographic keys. This includes generating, using, storing, archiving, and deleting keys, as well as limiting access to the keys physically, logically, and through user-role access.

As a general rule, the lifetime of a key is inversely proportional to the sensitivity of the data it protects. In other words, as data becomes more sensitive, the life of the key protecting it decreases (it's expiration period is reduced).

Token.io uses PKI to secure communications between the Token.io cloud and its clients. Public keys are stored in the Token.io cloud and are publicly shared, requiring valid signatures to be exchanged. Private keys are never shared. Each Token.io API invocation is digitally signed by the caller using its private key(s). The Token.io cloud and connected banks verify each API request generated by the Token.io TPP SDK using the caller’s public key.

Membership

In the context of Open Banking, Token.io classifies each third-party provider (TPP) and connected-bank customer as "members" having specific access permissions to connect with one or many banks via the Token.io cloud. A TPP is a business member and a bank customer is a user member. A business member is assigned a member ID. A user gets — you guessed it — a user ID.

The SDK's createMember method generates your memberId and establishes a unique Alias that no other business member can use, so you can connect with banks and be properly identified. Of equal importance, the TokenClient class defines where your private keys will be stored and accessed (see Cryptography – Keys and Key Management). Alias can be your business web domain, an email address, or your eIDAS certification, depending on the Alias.Type you choose.

In the event you forget your memberId, you can quickly look it up based on an Alias. If you forget an Alias, you can look it up using your memberId. The mechanics of membership are covered in Onboarding.

Token.io services architecture

Services are units of software that perform a function. They are used to break complex problems into a series of simpler problems. Services are also designed to be separately deployable, allowing Token to build highly scalable and resilient systems.

A high tolerance to various stresses and failures under real word conditions is called resilience. Token.io's services architecture builds systems that continue to function when things fail by making them autonomous, thereby eliminating single points of failure (SPOF). These services are then deployed to the Token.io cloud infrastructure and scaled up or down on demand. Hence, when one service instance fails, the detects this and automatically finds or creates another instance of the service that is working. This is called failover.

A high-level structural view of Token.io's services architecture looks like this (click to enlarge):

Depending on the Token.io-connected bank, Token.io's Bank SDK is implemented either directly, interfacing with the bank's Open Banking API, or through Token.io, utilizing Token.io's Bank Integration SDK. The Bank Integration SDK communicates with the Token.io Platform (also called the Token.io cloud) through Bank Adapter middleware and an Integration Service, which transform (translate) and segregate requests and responses to and from the Token.io cloud into data objects understandable by the disparate systems — the bank's Core Banking System on one side and Token.io's Open Banking Service on the other. Token.io's Core Service similarly coordinates the request-reply information flow to and from registered and verified TPP members, managing the token creation-redemption-cancellation/expiration lifecycle. Token.io's Member, Consent, and Directory services handle TPP member enrollment and service access (AIS/PIS), authentication (SCA), and licensing and certification (eIDAS) verification, respectively. Securely relaying open banking requests by TPPs and the corresponding responses from the bank is achieved through a Gateway hosting Token.io's gRPC interface and a REST API for direct TPP communications. Indirect TPP application integration is supported by the TPP SDK, which is available in multiple programming languages (Java, Javascript, and C#) and which interfaces with the gRPC protocol buffers. System Administration and Monitoring of SaaS operations complete the architecture with secure management visibility and control services.

The foregoing, all working together, enable easy integration with your existing IT infrastructure, delivering bank connectivity to TPPs via a single connection. Moreover, just as bank integration can be accomplished directly or through Token.io, TPP integration can be direct-to-bank or through Token.io, as well. TPPs choosing the latter course (through Token.io) can use their own licence or Token.io's licence. Ultimately, this distinguishes TPPs into three types:

  • TPPs connecting to Token.io's network of banks using Token's licence

  • TPPs connecting to Token.io's network of banks using their own licence

  • TPPs connecting directly to a specific bank using their own licence

An additional level of classification involves resellers. See TPPs versus Resellers for additional information.

Connect to Token.io

Connecting to the Token.io platform often means rapidly preparing your environment for integration, and a fast-tracked implementation may lead to common fundamentals being overlooked. At Token.io, we're proud proponents of site reliability engineering and firm believers in sharing tools and knowledge. Hence, should you require assistance with any aspect of the information in the preceding topics or those that follow here, please contact our support team. We'll strive to help resolve any issues you encounter.

In the meantime, let's take a brief look at potential connectivity pain points with an eye to avoiding unnecessary server-to-server communication issues in terms of:

Protocols

A protocol is a set of rules that govern the data communication mechanisms between clients (for example web browsers used by internet users to request information) and servers (the machines containing the requested information).

Protocols usually consist of three main parts: Header, Payload and Footer. The Header, placed before the Payload, contains information including source and destination addresses as well as other details (such as size and type) regarding the Payload. Payload is the actual information transmitted using the protocol. The Footer follows the Payload and works as a control field to route client-server requests to the intended recipients along with the Header to ensure the Payload data is transmitted free of errors.

Token.io leverages the gRPC protocol to exchange protocol buffers between server applications (our clients' applications) and client applications (Token.io cloud). gRPC permits a client application to directly call a method on a remote server application as if it were a local object, making it simple to create distributed services (which is effectively what the Token.io cloud is — a massive, distributed application linking banks to TPPs and users).

In order to operate in the manner required, gRPC makes use of HTTP/2 for its binary framing and compression capabilities, as well as HTTP/2's native support for connection multiplexing. Whilst a service may support HTTP/2, it may not support the trailing headers implemented by the gRPC protocol. This is a common issue that can create complications in environments not accustomed to serving HTTP/2 or gRPC. It's also an issue that can be easily overcome.

Load balancers

Load balancers at the cloud or network edge are typically the first devices to receive a connection from a source ultimately seeking to connect with a destination within an organisation's environment. With respect to the Token.io cloud, this entails connecting to the SDK operated by our client. However, not all load balancers are created equal. Some have full support for HTTP/2, some have only partial support, and others refuse to accept HTTP/2 altogether. Understanding the difference and why it exists is key to a successful implementation.

Google Cloud load balancers fully support HTTP/2 and merely require creating a load balancer, pointing a public IP address at its outside interface, then configuring a listener pool to receive traffic. Seeing that Google drove the initial development of gRPC, it's no surprise that its load balancers include native L7 support for gRPC and HTTP/2.

Within Amazon Web Services (AWS), the waters begin to muddy somewhat. A network load balancer with TCP listeners is fully compatible because it's an L4 load balancer that distributes TCP connections to hosts within the associated target group. A network load balancer becomes incompatible the moment a TLS listener is provisioned, since it effectively makes the load balancer intercept TLS negotiation and pass a non-comforming connect to the application within the target group. Thus, when using an AWS NLB, you simply create TCP listeners and never worry about your load balancer again.

In October 2020, AWS introduced full end-to-end HTTP/2 support in its Application Load Balancer (ALB) which also encompasses full support for the gRPC protocol.

If you are running your services on Azure, look to their layer 4 Azure Load Balancer, which supports load balancing TCP and UDP connections, meaning that it will not interfere with the higher level protocols used by gRPC. Support for gRPC is not provided at all with Azure’s App Service because these are hosted within Internet Information Server (IIS), which does not support gRPC. With regard to Azure Container Instances (ACI), problems have been detected with Windows-based images. However, implementing the Token.io SDK within a Linux container is known to work.

While Token.io lacks the ability to test your vendor security and load balancing products, issues are known to exist with the following:

  • F5 devices do not support gRPC, even with an HTTP/2 profile for a pool enabled. This limitation is a result of gRPC utilizing mandatory trailing headers (trailers) within its specification. At present, F5 devices can be made to work by enabling SSL Pass Through for the pool. A bug has been filed for this at https://support.f5.com/csp/article/K61517014

  • Neustar, a cloud based DDoS service, leverages Citrix Netscaler devices as their proxying layer and relies on Citrix for gRPC support. At present, Neustar requires engineering support to enable HTTP/2 for a given application profile. When configured, TLS connections terminate within their service and results in mangled gRPC frames reaching the Token.io SDK.

The takeaway here is that your mileage may indeed vary when it comes to your load balancer's support for HTTP/2 and gRPC. It is worth taking a look at your load balancer documentation to see if HTTP/2 is supported, and if so, how and to what extent? Many devices will accept an inbound HTTP/2 connection and pass on HTTP/1.1 connections to any target for which it is configured to pass traffic.WAF devices, such as Barracuda's WAF, are an example of this limitation. Others may support HTTP/2, but lack the ability to support gRPC frames as their implementation does not support trailing headers, a distinction that is important to consider when implementing Token.io’s SDK.

Proxy servers

In environments where a proxy server is mandated for outbound connections to services on the Internet, Token.io SDKs support common proxy directives as environment variables or parameters passed to the runtime. HTTP_CONNECT proxies are supported in gRPC by default. Use the following settings to support your respective SDK.

Java SDK proxy support

To support proxy servers from the Java SDK, pass these flags to the JVM:

-Dhttp.proxyHost=proxy -Dhttp.proxyPort=port

-Dhttps.proxyHost=proxy -Dhttps.proxyPort=port

To bypass the proxy for addresses your application may need to support, add:

-Dhttp.nonProxyHosts="localhost|127.0.0.1|10.*.*.*|*.domain.tld"

C# SDK support

To have your Token.io C# SDK-based application honour your network's proxy settings, set the following environment variables:

Environment.SetEnvironmentVariable("http_proxy", "<http://proxy:port>");

Environment.SetEnvironmentVariable("https_proxy", "<https://proxy:port>")

To bypass the proxy for addresses your application may need to support, add:

Environment.SetEnvironmentVariable("no_proxy", "127.0.0.1")

Environment variables

The gRPC core libraries support common proxy variables in the following forms:

HTTP_PROXY="<http://proxy:port>"

HTTPS_PROXY="<https://proxy:port>"

To bypass the proxy for addresses your application may need to support:

NO_PROXY="localhost,127.0.0.1,10.0.0.0/24,*.domain.tld"

Mutual TLS

Token.io uses Mutual TLS (mTLS) to authenticate sessions between Token.io cloud and servers built with our SDKs. In brief, mTLS is invoked when both the server (the application built with the SDK) and the client (Token.io cloud) present certificates to validate their identity. Once TLS is mutually verified, communication between the two entities can commence.

Configuring mTLS

Within the application integrating with the SDK, a certificate and key must be provided. These sample applications demonstrate the structure:

Java JavaScript C#

PFM example

PFM example

PFM example

Merchant example

Merchant example

Merchant example

These will live in the config/tls directory within your project root.

To configure your integrated SDK application for mTLS:

  1. Generate a cert.pem and a key.pem

  2. Share the cert.pem with Token.io via a support ticket (https://support.token.io)

  3. Let Token.io upload the cert to our trust store.

Within the config/tls directory, you will find a file called trusted-certs.pem. This contains the root CA, intermediate and leaf certificates for Token.io's sandbox and production environments (api-gprc.sandbox.token.io and api-grpc.token.io, respectively). These are the certificates that Token.io will present when connecting to the application built with the SDK.

Self-signed certificates

Token.io provides a script for creating self-signed certificates for use with mTLS. This script creates a private key and a self-signed certificate that is suitable for mTLS communication between entities, and is the lowest friction approach to implementing mTLS. The script will replace the cert.pem and key.pem files packaged with the sample applications.

Third-party authority certificates

If you wish to use a certificate from a third party certificate authority, you are more than welcome to do so; in which case, key.pem is replaced with the output of the key created during CSR, and cert.pem is replaced with the certificate returned to you by your certificate authority. If your CA is not a root CA, you will need to ensure that you send your certificate bundle to Token.io, in addition to cert.pem, so that we have your full certificate chain and can validate your leaf certificate (cert.pem) against the root and intermediate certificates provided with the bundle. All certificate issuers include instructions on accessing the bundle within their proprietary documentation.

TPPs versus Resellers

An organisation which interacts with a bank to provide services to consumers is a third-party provider (TPP). TPPs enable customers to make and receive payments directly from a bank account, make better use of their financial transaction data, or benefit from new card-based offerings. In the sense that the first party is generally a bank customer and the second party is typically the bank, the technology provider that connects them together becomes the third party. Put a different way, in a traditional relationship with a bank, the consumer interacts directly. In Open Banking, the consumer interacts with the TPP, which then interacts with the bank on the consumer's behalf.

TPPs can choose to integrate with banks on their own or through an aggregator. A Technical Service Provider (TSP) is one type of aggregator; a Reseller is another type. Token is a TSP. Aggregators providing Open Banking connections hosted on the Token.io Platform to other TPPs are Resellers.

The Token.io Platform supports two types of TPPs: (1) TPPs that provide Open Banking services under Token.io's licence and (2) TPPs that provide Open Banking services under their own licence.

By regulation, TSPs like Token.io provide purely technical services only — processing and storing data, privacy protection, and/or providing an IT and communication infrastructure — without taking possession of transacted funds or a user's account information, never directly handling funds and information in the role of either a PIS or AIS.

Resellers can leverage the Token.io Platform as a hosted TSP, a PISP or AISP or both. In general, Resellers can offer TPPs faster launching in a new market, access to compliant interfaces, technical simplicity, a single integration, and the convenience of using the Reseller's own verified eIDAS credentials for safe, secure access to the ever-growing network of Token.io-connected banks. Resellers can also assist TPPs that want to operate under the TPP's own licence and/or provide proprietary interfaces to sub-TPPs hosted on the Token.io Platform.

Within the Token.io ecosystem, TPPs are classified by four types:

When granted Partner Permissions by Token.io, TPPs using Token.io's licence register, onboard and manage their own sub-TPPs (merchants and/or PFMs). By contrast, a TPP operating under its own verified NCA licence extracted from its validated QSealC or QWAC can opt to administer its own realm , creating and maintaining its own bank connections. The preferred paradigm for most TPPs with Partner Permissions, however, is to operate under Token.io's realm to onboard and manage sub-TPPs.

These Token.io-Reseller-TPP chains take the respective forms that follow (click to enlarge).

TPPs using Token.io's licence

The TPPs in this category operate under the aegis of Token.io's licence, inheriting Token.io's bank configurations. Identified by a unique memberId, granted access using their own API authentication credentials, these TPPs can create and maintain user accounts, providing Token.io-hosted Open Banking services (PIS, AIS,).

Use Cases: Clients wishing to use Token.io's licence and integrate its API and Web App interface to connect with banks as simply as possible.

TPPs using their own licence

TPPs in this category operate under their own licence. Creating and maintaining their own bank registrations and configurations identified by their unique memberId, they are granted access using their own API authentication credentials, which allows them to create and maintain user accounts and provide Token.io-hosted Open Banking services.

Use Cases. TPPs with their own license wishing to use the Token.io API to connect to banks but which do not require any further structure in Token.io's environment for their clients.

TPPs using Token.io's licence with Partner permissions

TPPs in this category are like TPPs using Token.io's licence in the first category, except that these TPPs have been granted Partner permissions. This means that they can create Sub-TPPs that also operate under Token.io's licence. A unique actingAs.refId assigned when onboarded is then verified against the Sub-TPP's Open Banking permissions in each API call made on its behalf by the TPP-Partner.

Use Cases. TPPs wishing to resell Token.io's licence using the same API credentials for each Sub-TPP client.

TSP-Resellers using their own licence with Partner permissions

TPPs in this category are true TSP-Resellers operating under their own realm, rather than Token.io's, supporting (a) sub-TPPs using the Reseller's licence, as well as (b) TPPs using their own licence. Identified by a unique memberId, these Resellers create and maintain their own bank registrations and configurations, and are granted Token.io Platform access using common API authentication credentials, which allows them to create and maintain user accounts and provide whitelabel interfaces and functionality to onboarded sub-TPPs. At the same time, these Resellers can also support TPPs operating under the TPP's own licence.

Use Cases

  • Token.io TPPs wishing to whitelabel and resell the Token.io API under a partner agreement and who therefore require a unique memberId for each merchant they support

  • TPPs that abstract the Token.io API for use within their own API

  • TPPs wishing to streamline the API credentials needed to interact with configured banks

  • TPPs that want to support TPPs with their own Sub-TPPs, as well as TPPs that use their own licence

New TPPs register and onboard by creating a Token.io Dashboard account. TPPs with Partner permissions register new Sub-TPPs via the dashboard.

To obtain Partner permissions, contact your Token.io representative for assistance with setting up a reseller account. Once the required partnership agreements have been executed, you'll receive unique login credentials that allow access to the Dashboard's TPP Manager and other reseller functionality, from which you can create and manage new TPPs and/or Sub-TPPs, as appropriate.