NAV Navbar
Logo sized for slate
Java JavaScript Objective-C

Token Network

Token provides software to major European banks enabling truly open banking: any third-party developer can now easily and securely write applications that initiate payments and retrieve account information.

Our Token network provides a global open banking API that leverages existing bank infrastructure, in a PSD2-compliant fashion.

At the core of the Token API is the idea of a smart token, which provides authorization to access an underlying asset. The smart tokens are programmable by defining conditions (rules) that govern access to the asset.

The diagram describes the Token network at a high level.

Image showing Token network

Members

Members are the actors in the Token network who exchange funds or information through open, secure transactions. End users (customers/payers), merchants, and third-party providers are all members of the Token network.

Using the Token SDKs, you can create member entities and link them to bank accounts.

Token Cloud

The Token cloud is the layer through which Token network members communicate. It connects the banks on the backend to the Token network’s members, facilitating the exchange of funds and information. Anyone with a Token member account can use the API, and the easiest way to get started is to use one of the Token SDKs.

The Token cloud is distributed, with services hosted on geographically dispersed servers operated by Token and its partners.

Banks/Financial Institutions

Banks and other financial institutions are responsible for providing access to user information and for facilitating transactions. The Token cloud is integrated with banks/financial institutions through a thin integration layer that allows access to a bank’s core banking services.

Smart Tokens

A smart token is an authorization to access an underlying asset. Akin to “smart contracts”, smart tokens are programmable by defining conditions that govern access to the smart token’s asset. A smart token masks its underlying asset, such as an account number. Smart tokens are immutable: neither a smart token’s asset nor its conditions can be changed after the smart token is created. Every smart token has a unique Token ID.

There are two kinds of smart tokens:

The diagram shows the components of a smart token.

Image showing smart token components

The smart token contains:

Transfer Tokens

Transfer tokens provide authorization to transfer assets, such as the funds in a bank account. A transfer token’s conditions make transfer tokens much more powerful than typical payment API functions.

Access Tokens

Access tokens provide authorization to access customer information. An access token’s conditions control what can be accessed (that is, the asset), who can access the asset, and how the asset can be accessed.

Smart Token Lifecycle

The smart token lifecycle is the same for transfer tokens and access tokens.

An asset owner is the party whose asset is contained in the smart token.

Image showing smart token lifecycle

  1. Request. A Token member requests a smart token from another party; for example, a merchant asks a customer for a payment (which requires a transfer token) or for information such as a shipping address (which requires an access token).

  2. Create. Any Token member can create a smart token by calling the Token API. (See Create a Transfer Token and Create an Access Token.)

  3. Endorse. The asset owner—for transfer tokens, the payer; for access tokens, the grantor—endorses the smart token by digitally signing it. (See Endorse a Transfer Token and Endorse an Access Token.)

  4. Redeem. After the asset owner endorses the smart token, its token ID is given to the asset redeemer—for transfer tokens, the payee; for access tokens, the grantee—for redemption. The redemption process varies depending on the type of smart token. (See Redeem a Transfer Token and Redeem an Access Token.)

  5. Cancel. At any time during the lifecycle (not just as the last step as listed here), either party can cancel the smart token. Typically, it is the asset owner who cancels a smart token. (See Cancel a Transfer Token and Cancel an Access Token.)

Security

The Token network provides a high level of security for all parties—end users, merchants, organizations, banks, and financial institutions.

Authentication

The Token network uses PKI (public key infrastructure) to secure communications between the Token cloud and its clients (Token members and banks/financial institutions). Public keys are stored in the Token cloud, are publicly shared, and require valid signatures to be changed. Private keys are never shared. Each Token API invocation is digitally signed by the caller using its private key(s), and the Token cloud and banks verify the API request by using the caller’s public key. The Token SDKs greatly simplify the development process by wrapping the PKI complexity in a set of simple interfaces.

Image showing Token security model

The Token network supports the SCA (strong customer authentication) requirements of PSD2, whereby transfers over a threshold amount require 2FA (two-factor authentication). 2FA requires that authentication include any two of the following:

Key Management

During the Token member registration process, the Token SDKs generate three keys for the Token member:

Public Keys

The Token cloud manages and maintains a secure directory that enables username resolution and mapping of Member IDs to public keys. The entries in the directory are chained and cryptographically verifiable. To add or delete a key, a Token member must sign the add/delete request with their existing key.

Private Keys

Private keys are never uploaded to the Token cloud or shared with any entity in the Token network.

Merchants, banks, governments, and other organizations can store their private keys in accordance with their existing security requirements. Typical approaches are to use an HSM (hardware security module) or cloud-based HSM.

Users’ private keys are stored in their end user devices—mobile phone apps and browsers.

SDKs

Token open source SDKs simplify the interactions with the Token global open banking REST/gRPC API. The Token SDKs handle digital signatures and, where applicable, chain Token API calls. This makes it easier to develop Token- integrated applications, while providing most of the flexibility of the full Token API.

Java SDK

Requirements

To use the Token Java SDK, you must have Java Development Kit (JDK) version 8 or later.

Distribution

JavaScript SDK

The JavaScript SDK can be used by browsers and Node.js.

Installation

Token requires a recent version of npm/yarn to build.

Install the npm package:

npm install token-io

Usage

For usage examples, go to the How To’s section, or look at the generated docs.

Usage examples use the ES7 feature async/await. This is to keep the code simple and clean. If ES7 features are not available for your environment, the calls can be used with promises:

payer.cancelToken(tokenId)
  .then(function(res) {
    console.log(res);
  })
  .catch(function(err) {
    console.log(err)
  });

Objective-C SDK

As of this document’s writing, the Objective-C SDK has been tested on iPhone 6 with iOS 10 and later.

For early access to an evaluation build, contact Token.

Other Languages

To use a language other than the Token SDK languages (currently Java, JavaScript, and Objective-C, with additional languages to be added), you can use the Token gRPC or HTTP API.

For information about how to access and use the Token APIs, contact Token.

Website Integration

The Token JavaScript client library enables merchants to easily add a Token payment option to their website checkout. Merchants (and other third parties) can easily obtain smart tokens from users redeem the smart tokens by using the Token SDKs.

The diagram shows a typical website implementation that includes a Quick Checkout button with the Token logo.

Image showing merchant website implementation

For more information, contact Token.

How To’s

The following scenarios are typical workflows in the Token network. In general, they are applicable to any Token-integrated application.

Full source code for all samples is available from the Token Artifactory.

Create a Member

Create a member

Member createMember(TokenCluster tokenCluster) {

    // Initialize Token SDK instance.
    Token sdk = Token.builder()
            .connectTo(tokenCluster)
            .timeout(Duration.ofSeconds(15))
            .build();

    // Create a member account.
    return sdk.createMember("john_doe");
}
async function createMember() {

    // Initialize Token SDK instance.
    const TokenLib = require('../../src');
    const sdk = new TokenLib(TEST_ENV);

    // Create a member account.
    return await sdk.createMember("john_doe", Token.MemoryCryptoEngine);
}
Objective-C sample code coming soon.

Creating an account for a Token member is the first operation in the Token workflow. A Token member is associated with a username, which uniquely identifies the member in the Token network. Although a username must be chosen when a member is created, additional usernames can be added later.

Prerequisites

What to do next

Link a member and a bank account

void linkBankAccount(Member member) {

    // This sample simulates the standard linking flow
    // by generating it with a fake bank.
    List<SealedMessage> encryptedLinkingPayloads = member
            .createTestBankAccount(1000.0, "EUR")
            .getPayloadsList();

    // Finish account linking flow initiated by the user.
    member.linkAccounts(
            "iron" /* bank code */,
            encryptedLinkingPayloads);
}
async function linkBankAccount(member) {

    // This sample simulates the standard linking flow
    // by generating it with a fake bank.
    const res = await member.createTestBankAccount(1000.0, 'EUR');

    // Finish account linking flow initiated by the user.
    await member.linkAccounts(res.bankId, res.payloads);
}
Objective-C sample code coming soon.

To make payments, a Token member must link a bank account with its member identity (its Token member ID). The account must belong to a participating bank in the Token network.

The typical scenario is for a consumer to use a Token-integrated bank website and the Token PSD2 iOS app to complete the Token linking process, as follows:

  1. The Token app displays a list of banks that are supported by Token.

  2. The user selects a bank, and the Token app pops up a web view and navigates to the bank linking page.

  3. The user enteres their bank credentials and selects accounts to link.

  4. The bank linking flow finishes. The Token app extracts the encrypted account linking payload (the data contained in the request’s response) from the internal Token service to which it has been redirected by the linking flow.

The preferred method of linking real money bank accounts is to follow the steps in the Token PSD2 iOS app, available from the Apple app store. For test purposes, the Token SDKs provide methods to link with a test bank account.

Prerequisites

What to do next

Either of the following:

Make Payments

Making payments is one of the most fundamental operations in the Token network and is designed in accordance with PSD2 requirements.

To make a payment (that is, to transfer funds between two Token members), a transfer token is required to authorize the money transfer. For example, a merchant might request a transfer token to collect payment for an online purchase.

In this case, the merchant initiates the request for the transfer token, which is the “smart contract” between the merchant (payee) and the customer (payer). From the customer’s perspective, the terms of the contract are, “I, the paying member, allow a payment from my account #12345 at Iron Bank to pay €100 for online order #79262212. Payable to Online Merchant XYZ. Signed by Paying Member.”

The payer Token member (customer) accepts the terms of the contract by digitally signing (endorsing) the transfer token.

At order shipment time, the payee Token member (merchant) redeems the token to initiate the actual transfer of funds.

Create/Endorse a Transfer Token

Create/endorse a transfer (payment) token

Token createTransferToken(
        Member payer,
        String payeeUsername) {

    // Create a transfer token.
    Token transferToken = payer.createToken(
            100.0,
            "EUR",
            payer.getAccounts().get(0).id(),
            payeeUsername,
            "Book purchase");

    // Payer endorses a token to a payee by signing it with
    // her secure private key.
    transferToken = payer
            .endorseToken(transferToken, Key.Level.STANDARD)
            .getToken();

    return transferToken;
}
async function createTransferToken(payer, payeeUsername) {

    // Create a transfer token.
    const transferToken = await payer.createTransferToken(
            (await payer.getAccounts())[0].id,
            100.0,
            'EUR',
            payeeUsername);

    // Payer endorses a token to a payee by signing it with
    // her secure private key.
    const result = await payer.endorseToken(transferToken);

    return result.token;
}
Objective-C sample code coming soon.

Creating a transfer token is the first step in the payments process. This transfer token specifies the terms (such as amount, conditions, payer, and payee), and authorizes the payment.

Transfer tokens can be created with many combinations of a token’s conditions:

Image showing transfer token creation

The diagram shows the creation process for transfer tokens. Steps 1 and 2 correspond to Token SDK calls; the remaining steps are internal Token processes.

  1. End user creates the transfer token.
  2. End user endorses (signs) the transfer token.
  3. Token cloud authenticates, signs, and persists the transfer token.
  4. Token cloud sends the user-and-Token-signed transfer token to the bank.
  5. Bank signs the transfer token.
  6. Bank returns the fully-signed transfer token (signed by the end user, the Token cloud, and the bank) to the end user.
  7. Transfer token’s ID is sent to the redeemer.

Prerequisites

What to do next

Either of the following:

Redeem a Transfer Token

Redeem a transfer (payment) token

Transfer redeemTransferToken(
        Member payee,
        String tokenId) {

    // Retrieve a transfer token to redeem.
    Token transferToken = payee.getToken(tokenId);

    // Payee redeems a transfer token. Money is transferred
    // to a payee bank account.
    Transfer transfer = payee.redeemToken(transferToken);

    return transfer;
}
 async function redeemTransferToken(payee, tokenId) {

    // Retrieve a transfer token to redeem.
    const transferToken = await payee.getToken(tokenId);

    // Payee redeems a transfer token. Money is transferred
    // to a payee bank account.
    const transfer = await payee.redeemToken(transferToken, 5, 'EUR');

    return transfer;
}
Objective-C sample code coming soon.

To initiate a payment request, you redeem a transfer token. During the redemption process, the Token cloud verifies the transfer token’s integrity, confirms that the signatures (endorsements) are valid, and ensures that there are sufficient funds in the given account to satisfy the transfer token’s conditions. If all the checks pass, the Token cloud sends the payment request to the bank to perform the actual money transfer.

Image showing transfer token redemption

The diagram shows the redemption process for transfer tokens. Only step 1 is performed by calling the Token SDK; the remaining steps are internal Token processes.

  1. Redeemer redeems the transfer token.
  2. Token cloud verifies the transfer token’s conditions.
  3. Token cloud sends the funds transfer request to the payer’s bank.
  4. Money moves from the payer’s bank to the payee’s bank using legacy payment rails.
  5. Payer’s bank signs a confirmation that money movement was initiated (but cannot confirm whether the money was successfully transferred).
  6. Payer’s bank sends the signed confirmation to the redeemer.

Prerequisites

What to do next

Any of the following:

Cancel a Transfer Token

Cancel a transfer (payment) token

TokenOperationResult cancelTransferToken(
        Member payer,
        String tokenId) {

    // Retrieve a transfer token to cancel.
    Token transferToken = payer.getToken(tokenId);

    // Cancel transfer token.
    return payer.cancelToken(transferToken);
}
async function cancelTransferToken(payer, tokenId) {

    // Retrieve a transfer token to cancel.
    const transferToken = await payer.getToken(tokenId);

    // Cancel transfer token.
    return await payer.cancelToken(transferToken);
}
Objective-C sample code coming soon.

A transfer token’s payer or payee can cancel a transfer token anytime, which cancels any future payments that the transfer token authorized. Neither previous payments nor pending payments are reversed or canceled.

Prerequisites

What to do next

Retrieve Information

The Token network enables Token members to allow other Token members to access their normally private data/information, or to perform operations on their behalf. This supports information retrieval as defined by PSD2.

Access tokens provide the required authorization. For example, a Token member might allow an AISP to access the transaction history of one or more bank accounts. The resultant access token might be specified as, “This AISP can access my checking account at Iron Bank until July 31, 2017 to retrieve balance and transaction history under this account. Signed Granting Member.”

Access tokens are multi-use; that is, they authorize access an unlimited number of times, until they are canceled.

Create/Endorse an Access Token

Create/endorse an access (information) token

Token createAccessToken(
        Member grantor,
        String granteeUsername) {

    // Create an access token for the grantee to access
    // bank account names of the grantor.
    Token accessToken = grantor
            .createAccessToken(AccessTokenBuilder
                    .create(granteeUsername)
                    .forAllAccounts());

    // Grantor endorses a token to a grantee by signing it
    // with her secure private key.
    accessToken = grantor
            .endorseToken(accessToken, Key.Level.STANDARD)
            .getToken();

    return accessToken;
}
async function createAccessToken(grantor, granteeUsername) {

    // Create an access token for the grantee to access
    // bank account names of the grantor.
    const accessToken = await grantor.createAccessToken(
            granteeUsername,
            [{ allAccounts: {} }]);

    // Grantor endorses a token to a grantee by signing it
    // with her secure private key.
    const result = await grantor.endorseToken(accessToken);

    return result.token;
}
Objective-C sample code coming soon.

Creating an access token is the first step in the information retrieval process. Endorsing an access token is the process of digitally signing it.

Image showing access token creation

The diagram shows the creation process for access tokens. Steps 1 and 2 correspond to Token SDK calls; the remaining steps are internal Token processes.

  1. End user creates the access token.
  2. End user endorses (signs) the access token.
  3. Token cloud authenticates, signs, and persists the access token.
  4. Token cloud returns the fully-signed access token (signed by the end user and the Token cloud) to the end user.
  5. Access token’s ID is sent to the redeemer.

Prerequisites

What to do next

Either of the following:

Redeem an Access Token

Redeem an access token

List<Account> redeemAccessToken(
        Member grantee,
        String tokenId) {

    // Access grantor's account list by applying access
    // token to the grantee client.
    grantee.useAccessToken(tokenId);
    List<Account> grantorAccounts = grantee.getAccounts();

    // Clear access token from grantee client.
    grantee.clearAccessToken();
    return grantorAccounts;
}
async function redeemAccessToken(grantee, tokenId) {

    // Access grantor's account list by applying access
    // token to the grantee client.
    grantee.useAccessToken(tokenId);
    const accounts = await grantee.getAccounts();

    // Clear access token from grantee client.
    grantee.clearAccessToken();
    return accounts;
}
Objective-C sample code coming soon.

To retrieve information or perform an operation on a Token member’s behalf, you perform a series of operations that together make up the redemption process for access tokens. (This is different from redeeming a transfer token, which requires just a single SDK call.) During the access token redemption process, the Token cloud verifies the access token’s integrity and confirms that the signatures (endorsements) are valid. If all the checks pass, the Token cloud provides the requested information or performs the specified operation.

Because access tokens are multi-use, the redemption process can be repeated indefinitely, until the token is canceled.

A typical operation sequence would be for an AISP to call useAccessToken to act as the member who granted account access, perform a getAccounts operation to obtain the granting member’s account list, and finally call clearAccessToken operation to cease acting as that granting member.

Image showing access token redemption

The diagram shows the redemption process for access tokens. Only step 1 is performed by calling the Token SDK; the remaining steps are internal Token processes.

  1. Redeemer uses (applies) the access token to access the grantor’s Token account.
  2. Redeemer, acting as the grantor, performs an action (such as retrieving an account balance) by making a Token SDK call.
  3. Token cloud verifies the access token’s conditions.
  4. Token cloud sends the request for the action to the appropriate Token system participant.

    In this example, the action in step 4 is to get the balance of the grantor’s bank account. For other actions, the remaining steps might be different.

  5. Grantor’s bank signs the response that contains the balance information.

  6. Grantor’s bank sends the signed response to the redeemer.

Prerequisites

What to do next

Cancel an Access Token

Cancel an access token

TokenOperationResult cancelAccessToken(
        Member grantor,
        String tokenId) {

    // Retrieve an access token to cancel.
    Token accessToken = grantor.getToken(tokenId);

    // Cancel access token.
    return grantor.cancelToken(accessToken);
}
 async function cancelAccessToken(grantor, tokenId) {

    // Retrieve an access token to cancel.
    const accessToken = await grantor.getToken(tokenId);

    // Cancel access token. (Id can be provided instead)
    return await grantor.cancelToken(accessToken);
}
Objective-C sample code coming soon.

An access token’s grantor or grantee can cancel an access token anytime, which prevents future information retrieval an any operations associated with the access token.

Prerequisites

What to do next

Errors

This section describes runtime errors thrown by the Token SDKs, such as program exceptions.

Java SDK Errors

The Token Java SDK throws the standard gRPC exceptions; for more information, refer to grpc-java Status.java.

Error Enum Value Meaning
OK 0 Operation completed successfully.
CANCELLED 1 Operation was canceled (typically by the caller).
UNKNOWN 2 Unknown errror; for example, a status value was received from an unknown errror-space, or an API call returned an error with incomplete information.
INVALID_ARGUMENTS 3 Client specified an invalid argument.
DEADLINE_EXCEEDED 4 Deadline expired before operation could complete.
NOT_FOUND 5 Requested entity (such as a file or directory) was not found.
ALREADY_EXISTS 6 Entity that you attempted to create (such as a file or directory) already exists.
PERMISSION_DENIED 7 Caller does not have permission to execute the specified operation.
RESOURCE_EXHAUSTED 8 A resource, such as a per-user quota or the file system is out of space, has been exhausted.
FAILED_PRECONDITION 9 Operation was rejected because the system is not in a state required for the operation’s execution.
ABORTED 10 Operation was aborted, typically due to a concurrency issue.
OUT_OF_RANGE 11 Operation was attempted past the valid range; for example, seeking or reading past the end of a file.
UNIMPLEMENTED 12 Operation is not implemented or not supported/enabled.
INTERNAL 13 Internal error.
UNAVAILABLE 14 Service is unavailable, most likely due to a transient condition that might be corrected by retrying.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 Request does not have valid authentication credentials for the operation.

Objective-C Errors

The Token Objective-C SDK throws the standard gRPC exceptions; for more information, refer to grpc status.h.

Error Enum Value Meaning
GRPC_STATUS_OK 0 Operation completed successfully.
GRPC_STATUS_CANCELLED 1 Operation was canceled (typically by the caller).
GRPC_STATUS_UNKNOWN 2 Unknown errror; for example, a status value was received from an unknown errror-space, or an API call returned an error with incomplete information.
GRPC_STATUS_INVALID_ARGUMENTS 3 Client specified an invalid argument.
GRPC_STATUS_DEADLINE_EXCEEDED 4 Deadline expired before operation could complete.
GRPC_STATUS_NOT_FOUND 5 Requested entity (such as a file or directory) was not found.
GRPC_STATUS_ALREADY_EXISTS 6 Entity that you attempted to create (such as a file or directory) already exists.
GRPC_STATUS_PERMISSION_DENIED 7 Caller does not have permission to execute the specified operation.
GRPC_STATUS_RESOURCE_EXHAUSTED 8 A resource, such as a per-user quota or the file system is out of space, has been exhausted.
GRPC_STATUS_FAILED_PRECONDITION 9 Operation was rejected because the system is not in a state required for the operation’s execution.
GRPC_STATUS_ABORTED 10 Operation was aborted, typically due to a concurrency issue.
GRPC_STATUS_OUT_OF_RANGE 11 Operation was attempted past the valid range; for example, seeking or reading past the end of a file.
GRPC_STATUS_UNIMPLEMENTED 12 Operation is not implemented or not supported/enabled.
GRPC_STATUS_INTERNAL 13 Internal error.
GRPC_STATUS_UNAVAILABLE 14 Service is unavailable, most likely due to a transient condition that might be corrected by retrying.
GRPC_STATUS_DATA_LOSS 15 Unrecoverable data loss or corruption.

JavaScript SDK Errors

The Token JavaScript SDK throws different types of HTTP errors. All errors are wrapped in an error object, with a message that contains the SDK method that failed, along with the reason for failure.

Glossary

Term Definition
2FA Two-Factor Authentication
asset owner Party whose asset is contained in the smart token—for transfer tokens, the payer; for access tokens, the grantor
access token Smart token that provides authorization to access information or perform operations
AISP Account Information Service Provider; for example, Yodlee and Mint
API Application Programming Interface; for example, the underlying functions of the Token Java SDK
endorsement digital signature
grantee Token member who is authorized by another Token member (grantor) to retrieve information and perform operations on behalf of the grantor
grantor Token member who authorizes another Token member (grantee) to retrieve information and perform operations on his/her behalf
HSM Hardware Security Module
payee Merchant that receives money in exchange for goods
payer Consumer (end user or shopper) who makes a purchase and uses Token to pay the payee
PII Personally Identifiable Information
PISP Payment Initiation Service Provider; that is, online merchants
PKI Public Key Infrastructure; rules, datastores, and trusted entities that manage public-key encryption
PSD2 Payment Services Directive 2
redeemer Token member who redeems a smart token: for transfer tokens, the payee; for access tokens, the grantee
RTS Regulatory Technical Standards
SCA Strong Customer Authentication; a requirement of RTS for PSD2
SEPA Single Euro Payments Area; payment-integration intitative of the EU
smart token Authorization to access an underlying asset
SDK Software Development Kit; for example, the Token Java SDK
Token cloud Layer through which Token network members communicate
transfer token Smart token that provides authorization to transfer assets, such as the funds in a bank account

Copyright © 2017 Token, Inc. All Rights Reserved