Token Bank Integration

 ________   ________   ________    ___  __
|\   __  \ |\   __  \ |\   ___  \ |\  \|\  \
\ \  \|\ /_\ \  \|\  \\ \  \\ \  \\ \  \/  /|_
 \ \   __  \\ \   __  \\ \  \\ \  \\ \   ___  \
  \ \  \|\  \\ \  \ \  \\ \  \\ \  \\ \  \\ \  \
   \ \_______\\ \__\ \__\\ \__\\ \__\\ \__\\ \__\
    \|_______| \|__|\|__| \|__| \|__| \|__| \|__|
 ___   ________    _________   _______    ________   ________   ________   _________   ___   ________   ________
|\  \ |\   ___  \ |\___   ___\|\  ___ \  |\   ____\ |\   __  \ |\   __  \ |\___   ___\|\  \ |\   __  \ |\   ___  \
\ \  \\ \  \\ \  \\|___ \  \_|\ \   __/| \ \  \___| \ \  \|\  \\ \  \|\  \\|___ \  \_|\ \  \\ \  \|\  \\ \  \\ \  \
 \ \  \\ \  \\ \  \    \ \  \  \ \  \_|/__\ \  \  ___\ \   _  _\\ \   __  \    \ \  \  \ \  \\ \  \\\  \\ \  \\ \  \
  \ \  \\ \  \\ \  \    \ \  \  \ \  \_|\ \\ \  \|\  \\ \  \\  \|\ \  \ \  \    \ \  \  \ \  \\ \  \\\  \\ \  \\ \  \
   \ \__\\ \__\\ \__\    \ \__\  \ \_______\\ \_______\\ \__\\ _\ \ \__\ \__\    \ \__\  \ \__\\ \_______\\ \__\\ \__\
    \|__| \|__| \|__|     \|__|   \|_______| \|_______| \|__|\|__| \|__|\|__|     \|__|   \|__| \|_______| \|__| \|__|

TokenOS interacts with banks via APIs. A bank can provide tighter integration with TokenOS by implementing TokenOS’s bank integration API. (If a bank doesn’t implement this API, but does offer a public API, then TokenOS might use that other API. Implementing TokenOS’ bank integration API enables more features and smoother user experience for that bank.) By means of the TokenOS bank integration API, a bank can

Offer online merchants bank-direct payments capabilities with superior customer experience
Acquire new retail customers
Retain existing retail customers
Build new products and services for corporate clients
Offer clients products and services from the Token developer community

The Token Bank Integration Java SDK simplifies handling the TokenOS bank integration API. It handles network requests by calling Java methods; this allows programmers to concentrate on business logic instead of remote procedure call logic.

A Bank’s steps to integrating with TokenOS:

Get the Token Bank Integration SDK. Get the sample bank server implementation.
Generate keys and certificates for secure communication; keep track of them.
Set up fake environment/data for testing. This probably means setting up an environment with some fake accounts.
Get the sample bank server up and running. Normally this just works, but there are troubleshooting tips.
Ask Token to send test requests to the server. As the Bank gets some parts working with real functionality, Token can turn on more tests.
Replace fake parts of the sample bank server implementation with real implementations.
Set up a web interaction that authenticates a Bank customer and lets them choose accounts to link to Token.

The bank sets up a server that opens a port and listens for connections from TokenOS. Rather than implementing a server “from scratch”, a bank can start with the sample implementation. The sample responds to requests with preconfigured data; it doesn’t persist state, but instead “forgets” everything when reset.

API Overview

The bank server implementation handles TokenOS requests by defining methods. The Token Bank Integration SDK defines some interfaces. The bank implements these interfaces; when TokenOS sends a request to the bank, the SDK turns that request into an interface method call.

To handle these requests, a bank implements some interfaces. Depending on which features the bank will support, it must implement some or all of these:

AccountLinkingService (javadoc, description): Associates a Token member with Bank account(s)
- getBankAuthorization: get account linking information
AccountService (javadoc, description): Requests for bank account information.
- getBalance: get account balance
- getTransactions, getTransaction: get information about past transactions
- resolveTransferDestination: get transfer destination choices
- getAccountDetails: get detailed information about an account
TransferService (javadoc, description) Handles requests for transfers.
- transfer: Transfer funds
StorageService (javadoc) Handles requests to store key-value data. Keys are strings; values are binary “blobs”. Most banks won’t implement this service. Banks that don’t let Token store customer data in the Token Cloud implement StorageService.
- setValue: Store data
- removeValue: Delete data
- getValue: Return data
NotificationService (javadoc, description) Most banks won’t implement this service. A bank can register to deliver Token notifications to bank customers. Such a bank uses the Notification Service as part of delivering those notifications.
- notify: Deliver a notification

Many parts of the Bank Integration API work with a bank’s accounts: ask account balance, request transfer, and so on. A few parts of this API also refer to Token members, IDs of Token users. Where you see “account”, think bank account; where you see “member”, think Token member.

In TokenOS, an account has exactly one currency. Banks might support multicurrency bank accounts; to work with TokenOS, treat such an account as multiple Token “accounts”, one per currency. A TokenOS bank account has metadata. To “tag” one TokenOS account for one currency and another TokenOS for another currency, use metadata.

Moving money involves Transfers and Tokens. A Transfer represents a request to move money from one account to another. A transfer can have two Transactions associated with it: a debit at Bank A and a credit at Bank B. A Token is an authorization to access an underlying asset; when TokenOS keeps track of whether a payer authorizes a payment, it uses a Token to do so. You can learn more about Tokens.

// TokenOS treats these as distinct accounts:
BankAccount eurAcct = BankAccount.newBuilder()
  .setSwift(swift)
  .setAccountFeatures(features)
  .putMetadata("currency", "EUR")
  .build();
BankAccount gbpAcct = BankAccount.newBuilder()
  .setSwift(swift) // same
  .setAccountFeatures(features) // same
  .putMetadata("currency", "GBP") // different
  .build();

Account Linking Web Flow

The user sets up Token to link her bank account(s) with her Token member. Until the user has at least one bank account associated with her Token member, she can’t do any useful banking things.

The user interacts with the bank’s website to demonstrate authority over accounts; the user’s application sends proof of this interaction to Token; Token sends this proof to the Bank’s server, which responds with account linking information.

Overview / UI Flow

When a user wants to set up Token with her bank accounts at a Bank…

The user launches the Token app on her phone.
The Token app shows a list of banks. The user chooses her Bank.
The Token app shows a screen that prompts the user to log in to her Bank. This screen is a web view showing a web page provided by the Bank. When onboarding, the Bank told Token the URL of this page. Token passes in memberId=token member id and redirect_uri=uri as URL parameters.
The user logs in, sees a list of her link-able accounts; she checks those accounts she wants to link. This is a web form provided by the Bank web site.
The user OKs the web form. The Bank’s web site stores information about the linked accounts, associating that information with a “bearer token”: a short, unguessable string.
The Bank’s web site redirects to the location in the earlier-specified redirect_uri parameter, appending #access_token=bearer token string

When the web view’s location changes to this URL, the app gets the bearer token string and stops showing the web view.
The app uses the Token SDK to send this bearer token string to TokenOS.
Using the bearer token string, TokenOS requests linking information from the bank’s RPC server. The bank’s AccountLinkingService handles the request, returning a BankAuthorization structure containing the member ID and account information.
TokenOS links the accounts to the Token member. (The Bank does not need to write code to handle this request, unless it’s configured to not store customer data in the Token Cloud, in which case it implements StorageService.)

To get all this working, the Bank’s code must do a few things:

Set up a web UI flow separate from the Bank Integration API that has the user log in and choose from a list of accounts. This is described below.
Store account-choice information indexed by bearer token string such that it can be retrieved by the bank server’s AccountLinkingService.
Implement the AccountLinkingService.
Provision the Bank web site with a crypto configuration which the Bank shares with Token.

It’s normal to associate more than one Token member with a bank account. For example, if the bank account is a joint account, then more than one user might link their Token members with it.

Bank Web Site

As part of enabling Token linking, the Bank must set up some forms on the Bank web site, generate some data that links a Token member ID to their account(s), store that account-choice information, and redirect. (This implements the Implicit Grant part of the OAuth2.0 spec.)

Prompt the user to sign in; authenticate the user. Once she authenticates…
Present a form with a checkbox for each of the user’s bank accounts. If the user has some accounts which shouldn’t be Token-linkable, don’t show those accounts. If the user wants to Cancel, pretend she didn’t select any accounts and chose OK. If the user OKs…
Store the account choice information. Later, the Bank service will need to retrieve this information using a bearer token string. Thus, it might make sense to store this information in a database indexed on the bearer token string.
Redirect as described below.

The start of this flow should be an endpoint whose path ends in /authorize, e.g. https://sample-bank.com/token/authorize.

The Token app sets ?memberId=string&redirect_uri=string URL parameters when it shows the Bank’s sign-in web page. Keep track of these values, which are needed later. The member ID string is a Token member ID; it probably is not the same as the user’s Bank web site user name.

To respond to the client app with the bearer token string, redirect to the URI: redirect_uri#access_token=bearer token string. E.g., if redirect_uri is https://token.io/ and the bearer token string is ZmpkCmF, then redirect to https://token.io/#access_token=ZmpkCmF.

To instead respond to the client app with an error, redirect to the URI: redirect_uri?error=error string, where error string is one of invalid_request, access_denied, server_error, or temporarily_unavailable.

https//token.io?error=access_denied

Bank Integration SDK

The Bank programs a service to listen and respond to Token requests from the Internet. Token provides a Bank Integration Java SDK to ease this task. The Java SDK defines Java interfaces for the Bank to implement. It provides some code to convert structures sent over the network into simpler structures. Bank programmers can thus focus on core business logic.

The Sample implementation uses the Bank Integration SDK and uses its APIs.

The SDK defines a few interfaces. To support various Token features, a bank can implement some of these interfaces. If a bank will not support all Token features, it need not implement all of these interfaces. The interfaces are described in more detail below.

To get the latest Bank Integration Java SDK, browse https://token.jfrog.io/token/webapp/#/artifacts/browse/tree/General/public-libs-release-local/io/token/sdk/tokenio-sdk-integration and choose the latest version.

Maven

To depend on the SDK, tell Maven to use Token’s artifact repository:

<repositories>
    ...
    <repository>
      <url>https://token.jfrog.io/token/public-libs-release-local/</url>
    </repository>
</repositories>

Specify the artifact to depend on:

<dependency>
    <groupId>io.token.sdk</groupId>
    <artifactId>tokenio-sdk-integration</artifactId>
    <version>2.1.5</version>
</dependency>

Gradle

To depend on the SDK, tell Gradle to use Token’s artifact repository:

repositories {
  ...
  maven { url 'https://token.jfrog.io/token/public-libs-release-local/' }
}

Specify the artifact to depend on:

compile(group: 'io.token.sdk', name: 'tokenio-sdk-integration', version: '2.1.5')

Server Builder

Token Integration SDK provides a framework for wiring service implementations abstractions into a single Server running on a given port.

This example uses io.token.sdk.ServerBuilder to run a custom implementation of the Token Bank Service integrated with the Core Banking System of a partner bank.

This example starts a server listening on port 1234 and ready to serve requests from TokenOS. Its connectivity configuration was set up as part of onboarding.

You can optionally register an interceptor to execute some code at the start or end of any RPC request the server receives. Call the registerInterceptor method; this method uses InterceptorFactory which uses SimpleInterceptor.

This code uses the APIs:

Token Bank Integration

API Overview

Account Linking Web Flow

Overview / UI Flow

Bank Web Site

Bank Integration SDK

Server Builder

Service Interface Definitions

Common Objects

Money

Bank Accounts

Transactions

Account Balance

Account Linking Service

BankAccount Structure

BankAuthorization structure

Account Service

Account Balance

Transaction History

Transfer Destination Choices

Transfer Service

Notification Service

Onboarding

Information Banks Provide

Information Token Provides

Establishing TLS (SSL)

Troubleshooting the Sample Bank

Jetty ALPN/NPN has not been properly configured.

Testing TLS, Certs with openssl

API

Account API

Get Transaction

Get Transactions

Get Balance

Transfer API

Storage API

Set Value

Get Value

Remove Value

Notification API

Notify

`Jetty ALPN/NPN has not been properly configured.`

Testing TLS, Certs with `openssl`