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 use Smart Tokens to request and redeem customer payments.

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.

Full source code for all samples comes with your SDK. E.g., Java sample code comes with the Java SDK’s “sources” jar.

Create a Member

Create a member

    public static Member createMember(TokenCluster tokenCluster) {
        try (TokenIO tokenIO = TokenIO.create(DEVELOPMENT)) {
            return tokenIO.createMember(TestUtil.newUserName());
        }
    }
    // Initializes SDK
    const TokenLib = require('../../src');
    const Token = new TokenLib(TEST_ENV);

    // Generate a random-nonsense-string username.
    // ("john_doe" would be more typical than a random string.
    // But if we run this code with the same username twice,
    // the second time it will fail because the name's already taken.)
    const username = Token.Util.generateNonce();

    // Creates a member, with keys stored in memory
    return await Token.createMember(username, 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 test bank account

    /**
     * Links a Token member and a bank.
     *
     * <p>The bank linking is currently only supported by the Token PSD2 IOS mobile app.
     * This sample is implemented for a very high level illustration of the bank linking concept
     * and serves as an integral building block connecting other samples. The desktop version of
     * the bank linking process is in the development. Until it's ready, please use Token PSD2 IOS
     * mobile app to link Token members and banks.
     *
     * @param member Token member to link to a bank
     * @return linked token accounts
     */
    public static List<Account> linkBankAccounts(Member member) {
        // User opens a bank web site and completes the Token linking process. The following is a
        // high level description of how that happens in the Token PSD2 IOS mobile app:
        // 1. App displays a list of banks supported by Token
        // 2. User selects a bank, the app pops up a web view and navigates to the bank linking page
        // 3. User enters bank credentials and selects accounts to link
        // 4. The bank linking flow completes and the app extracts encrypted bank authorization
        //    from the internal service redirected to by the linking flow.

        // For the purpose of this sample, we simulate the entire linking flow described above
        // by generating it with a fake bank below.
        BankAuthorization encryptedBankAuthorization =
                member.createTestBankAccount(1000.0, "EUR");

        // Finish account linking flow initiated by the user.
        return member.linkAccounts(encryptedBankAuthorization);
    }
/**
 * Links a Token member and a bank.
 *
 * The bank linking is currently only supported by the Token PSD2 IOS mobile app.
 * This sample is implemented for a very high level illustration of the bank linking concept
 * and serves as an integral building block connecting other samples. The desktop version of
 * the bank linking process is in the development. Until it's ready, please use Token PSD2 IOS
 * mobile app to link Token members and banks.
 *
 * @param {Member} member - Token member to link to a bank
 */
export default async (member) => {
    // Generates a test bank account that we can link with
    const encryptedBankAuthorization = await member.createTestBankAccount(200, 'EUR');

    // Links the account, by sending the bank authorization
    const accounts = await member.linkAccounts(encryptedBankAuthorization);
}
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 enters 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

    public static Token createTransferToken(
            Member payer,
            String payeeUsername) {

        // Create a transfer token.
        Token transferToken =
                payer.createTransferToken(
                        100.0, // amount
                        "EUR")  // currency
                        .setAccountId(payer.getAccounts().get(0).id()) // source account
                        .setRedeemerUsername(payeeUsername) // payee token username
                        .setDescription("Book purchase") // optional description
                        .execute();

        // 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;
    }
    const accounts = await payer.getAccounts();

    // Payer creates the token with the desired terms
    const token = await payer.createTransferToken(100.00, 'EUR')
            .setAccountId(accounts[0].id)
            .setRedeemerUsername(payeeUsername)
            .execute();

    // Payer endorses the token, creating a digital signature on it
    const result = await payer.endorseToken(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

    public static Transfer redeemTransferToken(
            Member payee,
            String accountId, // account ID of the payee
            String tokenId) { // ID of token to redeem
        // 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,
                Destinations.token(payee.memberId(), accountId));

        return transfer;
    }
/**
 * Redeems a transfer token.
 *
 * @param {Member} payee - payee member
 * @param {string} tokenId - id of the token to redeem
 * @return {Object} transfer - created transfer
 */
export default async (payee, tokenId) => {
    // Payee gets the token to see details
    const transferToken = await payee.getToken(tokenId);

    // Destination for sending the funds
    const destination = {
        account: {
            sepa: {
                iban: '123',
            }
        }
    }

    // Payer redeems the token, getting a transfer
    const transfer = await payee.redeemToken(transferToken, 5, 'EUR', 'lunch', [destination]);

    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

    /**
     * Cancels a transfer token.
     *
     * @param grantor grantor Token member
     * @param tokenId token ID to cancel
     * @return operation result
     */
    public static TokenOperationResult cancelTransferToken(Member grantor, String tokenId) {
        // Retrieve a transfer token to cancel.
        Token transferToken = grantor.getToken(tokenId);

        // Cancel transfer token.
        return grantor.cancelToken(transferToken);
    }
/**
 * Cancels a transfer token.
 *
 * @param {Member} payer - payer member
 * @param {string} tokenId - id of the token to redeem
 * @return {Object} result - result of the token operation
 */
export default async (payer, tokenId) => {
    // Payer gets the token to see details
    const transferToken = await payer.getToken(tokenId);

    // Payer cancels the 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

Send an Attachment with a Token

                payer.createTransferToken(
                        100.0, // amount
                        "EUR")  // currency
                        .setAccountId(payer.getAccounts().get(0).id()) // source account
                        .setRedeemerUsername(payeeUsername) // payee token username
                        .setDescription("Invoice payment") // optional description
                        .addAttachment(
                                payer.memberId(),
                                "image/jpeg",
                                "invoice.jpg",
                                loadImageByteArray("invoice.jpg"))
                        .execute();
    const token = await payer.createTransferToken(100.00, 'EUR')
              .setAccountId(accounts[0].id)
              .setRedeemerUsername(payeeUsername)
              .addAttachmentData(
                  payer.memberId(),
                  "image/jpeg",
                  "invoice.jpg",
                  getImageData("invoice.jpg"))
              .execute();

A user can provide an attachment, roughly equivalent to a file, with a token. For example, buyer might include an image of a scanned import permit with their payment; a service provider might provide an invoice image along with a request for payment.

When building a transfer token, you can add attachments. For each attachment, provide a file name, MIME type (e.g., image/jpeg), and contents. The Token SDK APIs have attachments and blobs. Here, an attachment might not have the “file” contents. To download the contents, you want the blob associated with that attachment.

The Token SDK code uploads the attachment to the Token network along with the transfer token. The Token network uses the token’s permissions to control access to the attachment. Only those who can see the token can see the attachment.

Get an Attachment from a Token

        Token transferToken = payee.getToken(tokenId);

        List<Attachment> attachments = transferToken
                .getPayload()
                .getTransfer()
                .getAttachmentsList();
        for (Attachment attachment : attachments) {
            // Attachment has some metadata (name, type) but not the "file" contents.
            if (attachment.getType().startsWith("image/")) {
                // Download the contents for the attachment[s] we want:
                Blob blob = payee.getTokenBlob(tokenId, attachment.getBlobId());
                // Use the attachment data.
                showImage(
                        blob.getPayload().getName(),  // "invoice.jpg"
                        blob.getPayload().getType(),  // MIME, e.g., "image/jpeg"
                        blob.getPayload().getData().toByteArray()); // byte[] of contents
            }
        }
    const transferToken = await payee.getToken(tokenId);

    var allContents = [];

    for (var ix = 0; ix < transferToken.payload.transfer.attachments.length; ix++) {
        // attachments have metadata but not the "file" content
        const att = transferToken.payload.transfer.attachments[ix];
        // download the content of the attachment[s] we want
        const blob = await payee.getTokenBlob(tokenId, att.blobId);
        const blobContents = base64js.toByteArray(blob.payload.data);
        allContents.push(blobContents);
    }

A token might come with attachments, roughly equivalent to files. For example, buyer might include an image of a scanned import permit with their payment; a service provider might provide an invoice image along with a request for payment.

When you receive a token, you can decide whether to download the “file” contents of its attachments. The Token SDK APIs have attachments and blobs. Here, an attachment might not have the “file” contents. To download the contents, you want the blob associated with that attachment.

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

    /**
     * Creates an information access token to allow a grantee to see all bank accounts of a grantor.
     *
     * @param grantor Token member granting access to her accounts
     * @param granteeUsername Token member username acquiring information access
     * @return an access Token
     */
    public static 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;
    }
/**
 * Creates a access token and endorses it to a grantee.
 *
 * @param {Member} grantor - member that will give access
 * @param {string} granteeUsername - username of the member that will be granted access
 * @return {Object} token - endorsed token
 */
export default async (grantor, granteeUsername) => {
    // Grantor creates the token with the desired terms
    const token = await grantor.createAccessToken(granteeUsername, [{ allAccounts: {} }]);

    // Grantor endorses the token, creating and submitting a digital signature
    const result = await grantor.endorseToken(token);

    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

    /**
     * Redeems access token to acquire access to the grantor's account names.
     *
     * @param grantee grantee Token member
     * @param tokenId ID of the access token to redeem
     * @return list of grantor's accounts accessed by the grantee
     */
    public static 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;
    }
/**
 * Redeems an information access token token, in order to acquire names of the grantor's
 * accounts.
 *
 * @param {Member} grantee - grantee member
 * @param {string} tokenId - id of the token to redeem
 * @return {Array} accounts - grantor accounts
 */
export default async (grantee, tokenId) => {
    // Use the access token, now making API calls on behalf of the grantor, and get accounts
    grantee.useAccessToken(tokenId);
    const accounts = await grantee.getAccounts();

    // Clear the access token
    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

    /**
     * Cancels an access token.
     *
     * @param grantor grantor Token member
     * @param tokenId token ID to cancel
     * @return operation result
     */
    public static TokenOperationResult cancelAccessToken(Member grantor, String tokenId) {
        // Retrieve an access token to cancel.
        Token accessToken = grantor.getToken(tokenId);

        // Cancel access token.
        return grantor.cancelToken(accessToken);
    }
/**
 * Cancels an access token.
 *
 * @param {Member} grantor - grantor member
 * @param {string} tokenId - id of the token to cancel
 * @return {Object} result - result of the token operation
 */
export default async (grantor, tokenId) => {
    // Grantor gets the token to see details
    const accessToken = await grantor.getToken(tokenId);

    // Grantor cancels the token
    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

Subscribe to Member Notifications

Member has a subscribeToNotifications method:

    /**
     * Subscribes a device to receive push notifications.
     *
     * @param handler specify the handler of the notifications
     * @param handlerInstructions map of instructions for the handler
     * @return subscriber Subscriber
     */
    public Subscriber subscribeToNotifications(
            String handler,
            Map<String, String> handlerInstructions)
/**
 * Creates a subscriber to receive notifications of member events, such as step up auth,
 * new device requests, linking account requests, or transfer notifications
 *
 * @param {string} handler - who is handling the notifications
 * @param {string} handlerInstructions - how to send the notification
 * @return {Promise} subscriber - Subscriber
 */
 Member.subscribeToNotifications(
            handler = "token",
            handlerInstructions = {})
Objective-C sample code coming soon.

A Token client might invoke subscribeToNotifications to tell the Iron Bank where to deliver notifications.

/* Subscribe to notifications */
Map<String, String> handlerInstructions = new HashMap<>();
// These handler instructions can be any key-value string pairs; the bank decides the format.
// The bank uses them to deliver notifications to the user.
handlerInstructions.put("deviceID", "Z29vZgo");
Subscriber sub = member.subscribeToNotifications("iron", handlerInstructions);
String subId = sub.getId();
/* Subscribe to notifications */
// These handler instructions can be any key-value string pairs; the bank decides the format.
// The bank uses them to deliver notifications to the user.
var handlerInstructions = {"deviceID": "Z29vZgo"};
var subscriber = member.subscribeToNotifications("iron", handlerInstructions);
var subscriber_id = subscriber.getId();
Objective-C sample code coming soon.

The getSubscribers, getSubscriber, and unsubscribeFromNotifications(subscriberId) Member methods support other notification subscription management.

/* Unsubscribe from Iron Bank's old deviceID system, it's obsolete now. */
List<Subscriber> subs = member.getSubscribers();
for (Subscriber sub : subs) {
    if (sub.getHandler().equals("iron")
            && sub.getHandlerInstructionsMap().containsKey("deviceID")) {
        payer.unsubscribeFromNotifications(sub.getId());
    }
}
/* Unsubscribe from Iron Bank's old deviceID system, it's obsolete now. */
var subs = member.getSubscribers();
subs.forEach(function(sub) {
  if (sub.handler == "iron" && sub.handlerInstructions && sub.handlerInstructions.deviceID) {
     member.unsubscribeFromNotifications(sub.id);
  }
})
Objective-C sample code coming soon.

Token notifies members of important events. For example, if a merchant uses Token to ask a member for a payment, Token notifies the member to ask for approval. A Token client can register a Bank to deliver these notifications. We say it “subscribes” to notifications. Thus, if a Bank has some way to deliver notifications to a Token member, it can register to do so by having a client subscribe to the member’s notifications.

(This document only describes how a Token client app can subscribe to notifications. To learn how a Bank receives notifications to pass along, please see the Token Bank Integration documentation.)

When subscribing to a member, the client can provide a key-value map of handlerInstructions, where the keys and values are text strings. When a Bank gets a notification to pass along to the member, it also gets a copy of this handlerInstructions. Thus, set handlerInstructions to hold the information the Bank will need when it delivers a notification.

Other useful Member methods for managing subscribers:

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