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

Security benefits

This architecture ensures high security by preventing any single system from holding a complete, usable authorization token.

• No Single Point of Compromise: Neither the client nor the API Gateway's cache ever holds the complete token. An attacker would need to compromise both systems to reassemble and use the token.
• Opaque Client Token: The client receives only the Signature component, which acts as a non-decryptable, opaque reference key. This prevents the client from accessing or relying on the token's sensitive payload (head and body).

How it works

When the Token Service issues an authorization token, it immediately splits it into two distinct parts (analogous to a standard JWT structure):

The token assembly and caching flow

• The Token Service splits the token into the Signature and the Head/Payload.
• The Service sends the Signature half back to the Client.
• The Service then hashes the Signature part.
• The Service sends the Hash along with the Head and Payload to the API Gateway.
• The Gateway caches the token using the Hashed Signature as the cache key. The value is cached as long as the token's expiration time.

The request flow

When the client sends a subsequent request, the API Gateway performs the reassembly process:

• The Client sends the Signature component with its request.
• The API Gateway takes the Signature, hashes it, and uses the hash to look up the corresponding Head and Payload in its cache.
• The Gateway successfully retrieves and glues back the token—the Head, Payload, and Signature.
• The complete, validated token is then forwarded to the API Service handling the request, ready for deserialization and use.

Usage and persistence requirements

The Split Token is only provided immediately after being generated, with the Authorize event (/docs/event-notifications-webhooks), to the notification URL provided during Trustly onboarding.

A webhook listener must be configured at that URL in order to persist the splitToken alongside the correlating identifier (either the transactionId for a one-time payment or the customerId for saved credentials/recurring use).

Critical Warning: If the splitToken is not persisted, the transaction can only be "re-verified." This process will generate a new splitToken but will require the user to repeat the full authorization flow in the Lightbox, leading to a poor user experience.

API integration

Several Trustly APIs, such as the Capture endpoint (https://amer.developers.trustly.com/payments/reference/post-transactions-transactionid-capture), require the splitToken parameter.

The token is often constructed with the + character as a separator. For example:

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

URL Encoding is Required:

The Trustly API expects url-encoded form data. You must encode the splitToken string before passing it to the Trustly APIs.

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

const splitToken = encodeURIComponent("PUT_YOUR_SPLIT_TOKEN_HERE");