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 completes 2FA (two-factor authentication) triggered by the Bank, similar to their internet banking login process.
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.

IMPORTANT: The bank’s site must use https instead of http and the certificate must be from a valid Certificate authority, NOT a self-signed one.

(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

Guest Checkout

Payment Initiation Services (PIS)

User’s who make a purchase with Token have the option to complete the purchase without the necessity of a Token identity, even if their bank is integrated with Token. This is called Guest Checkout.

The user is redirected to their bank’s authentication page (login).
The user authenticates with the bank and chooses which account to use for payment.
The bank displays a confirmation of payment.
The user confirms the purchase with the bank.

Payment Initiation Flow

Diagram of Payment Initiation Flow

The bank provides Token with a bank_url endpoint.
The user proceeds to make a Guest Checkout.

Token hits the URL in the following format:

GET bank_url?auth-request-id=auth_request_id

The auth-request-id is a unique identifier used to retrieve the payload containing all information on the purchase as well as the final callback URL. This payload needs to be signed by the bank, hence the name (Token is requesting authorization from the bank).

When the bank receives the above information, it calls getAuthRequestPayload(authRequestId) using Token’s Bank SDK, where authRequestId is the unique identifier in the URL.
This call returns a TokenPayload containing information about the purchase as well as the callback url.
The bank displays its authentication pages for the user to authenticate, optionally including SCA (Strong Customer Authentication). This can be the same page as the one used for linking. If something goes wrong during authentication, the bank should redirect the user to the callback-url with the query parameter error and the received error code. This will be propagated back to the TPP.
After the user authenticates, the bank may create and display an account selection page for the user to choose which account they wish to pay from. If the user only has one account, this page may not be displayed. This page will need to be created by the bank.
Once the bank has the payload from Step 3 and the account the user chose in Step 5, it can retrieve the (refId, initiatorId) pair from the payload by calling payload.getRefId() and payload.getInitiatorId()

The bank is responsible for linking this pair with the user’s chosen account. When the payment is redeemed, Token sends a TransferRequest containing a (tokenRefId, tokenInitiatorId) pair to the bank (this pair is the same as refId and initiatorId). The bank should use this pair to look up the user’s chosen account and perform the transfer.
After the user selects the account, the bank displays the Payment Confirmation page containing information on the purchase. The bank parses and displays the payload from Step 3 on this page.
Once the user confirms the purchase, the bank signs the payload using Member: SignTokenPayload from the SDK and produces the bank_signature. The result of signTokenPayload needs to be base64 encoded, and the result of that is the signature param in the URL mentioned in Step 10.
The bank redirects the user using the callback_url in the following format:

callback_url?auth-request-id=auth_request_id&signature=bank_signature

When the merchant calls RedeemToken, Token sends a TransferRequest to the bank that contains the same (tokenRefId, tokenInitiatorId) pair mentioned in Step 6.

The bank uses this pair to look up its associated user account (described in Step 6 of Payment Initiation), and perform the actual transfer of funds.

NOTE: The Token Bank SDK is private. We will provide you with the Artifactory credentials for access. See this article for setting it up with Gradle.

Account Information Services (AIS)

The user has the ability to give TPPs access to their data through Token without the use of the Token App for directly integrated banks.

The user is redirected to the bank’s authentication (login) page.
The user authenticates with the bank and chooses which account they wish to grant the TPP access to (balance and transaction).
The bank displays a confirmation page.
The user confirms their consent for access.

Flow

Diagram of Access Information Flow

This flow can currently be achieved by following the same procedure described in the Account Linking section. If you have already implemented our account linking flow, you do not need to do anything more.

NOTE: While the Account Linking Section above describes the Token Mobile App, everything that is relevant to the Guest Access Flow also applies to the Token Web App.

Below is a high-level overview of the procedure:

The bank provides Token with a bank_url to the bank login page.
The user opens the Token web app on the AISP’s website.
Token shows a list of banks and the user chooses their bank.
They click Proceed as Guest, then Token redirects them to the bank login page (bank_url) with the query parameter linking-request-id=linking_request_id.
The bank calls GetLinkingRequest to obtain the TokenRequest, member_id, and callback_url.
The user logs in and sees a list of their linkable accounts; the user checks those accounts they want to link. This is a web form provided by the bank website.
The user “OK’s” the web form and the bank stores information about the linked accounts, associating that information with a short, unguessable string called a “bearer token”.
The bank’s web site redirects to the location in the earlier-specified redirect_uri parameter, appending the hash fragment #access_token=bearer_token.
The Token web app gets the bearer_token and sends it to TokenOS.
Using the bearer_token, 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 a temporary Token member. (The bank does not need to write code to handle this request unless it’s configured not store customer data in the Token Cloud, in which case it implements StorageService).

To make this work the bank must:

- Set up a web UI flow separate from the Bank Integration API that has the user login and chooses from a list of accounts. This is described above under Bank Web Site. - Store account-choice information indexed by bearer token string so it can be retrieved by the bank server’s AccountLinkingService. - Implement the AccountLinkingService. - Provision the bank web site with a crypto configuration the bank shares with Token.

NOTE: It’s normal to associate more than one Token member with a bank account. If the user is a guest user, Token will create a temporary Token member each time the flow is executed.

IMPORTANT: The flow described above is identical to the account linking flow. We are working on improving it for guest access, so expect changes in the future.

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')

If you are interested in building your app with Android or iOS embedded SDK, you can find them here

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_bulk_transfer_id`	required A transfer ID set by Token that references the bulk transfer
`ref_id`	optional A reference ID set by the initiator of the token request
`token_initiator_id`	required The member ID of the initiator of the token request
`total_amount`	required The total amount of the transfers, regardless of currency; used for redundancy checks
`transfers`	required The list of transfers in the bulk transfer
`source_account`	required The source account of the payment. Identifies the type of payment (example: Swift; SEPA)
`description`	optional A string describing what the payment is for

Token Bank Integration

API Overview

Account Linking Web Flow

Overview / UI Flow

Bank Web Site

Guest Checkout

Payment Initiation Services (PIS)

Account Information Services (AIS)

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

Standing Order

Transfer Service

Future-Dated Payments

Standing Orders

Bulk Payment

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

Embedded SDK

Fallback Solution

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

Testing TLS, Certs with `openssl`