The concept of a "Split Token" is used throughout the Trustly API. Upon a user authorization of a banking provider for use with Trustly's payments APIs, the data retrieved from the authorization is encoded and promptly split bit-for-bit. The client receives half of the token and Trustly persists the other half. This patent-pending "Split Token" architecture significantly increases the security of payment APIs.

How it Works

When token service is issued for a client, it splits the token into two parts:

• the signature of the token
• the head and body of the token

From there, the token service sends back the signature half to the client while the token service hashes the signature part and sends the hash with the second half (the head and body) to the API Gateway. The gateway then caches the token using the hashed signature as the key for the cache. The value is cached as long as the expiration time of the token.

When the client sends a request, the API Gateway takes the signature part sent by the client, hashes it and looks it up in its cache. Then it can glue back the token - the head, body and signature, and forwards it to any API service handling the request. Thus, the API gets a whole token, ready to be deserialized and used as needed.

Usage

The Split Token is only provided immediately after being generated, via the Authorize event, to the notification URL provided to Trustly during onboarding. A webhook listener must be configured at that URL in order to persist the splitToken alongside the correlating transactionId or customerId. If the splitToken is not persisted, the transaction can be "re-verified" and a new splitToken will be generated, but the user will be required to repeat the authorization flow in the Lightbox.

Several of Trustly's APIs, such as the Capture endpoint, requires usage of the splitToken parameter. Note that the token is often constructed with the + character as a separator. Example:

CO+s/6PxMBABGJ4QBIAAqSlsdBQe7ZP4tkduflU4Ft9+1ES5Sxgt2gsdg3lP/Qu+1yTUJiDv5dWZSCa9Z47wj1lag5xrc8zK2Z4U5

Since Trustly's API expects url-encoded form data, be sure to properly url encode the splitToken string before passing it to Trustly's APIs.

final String splitToken = java.net.URLEncoder.encode("PUT_YOUR_SPLIT_TOKEN_HERE");

const splitToken = encodeURIComponent("PUT_YOUR_SPLIT_TOKEN_HERE");