Tokens and Account Security

Trustly uses a combination of split token architecture and tokenized account numbers to secure payment data and bank account information throughout the transaction lifecycle.

Split Token

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, 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, 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.

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

1
const splitToken = encodeURIComponent("PUT_YOUR_SPLIT_TOKEN_HERE");

Tokenized Account Numbers (TAN)

Some financial institutions that support OAuth-based connections may return a Tokenized Account Number (TAN) when users link their accounts. A TAN is a standard account and routing number secure substitution that can be used for ACH and RTP transfers, and is reconciled by the issuing bank at settlement. Each application or merchant a user connects with receives a unique TAN instead of the user’s actual account number. This enables stronger access controls, allowing the user to monitor or revoke a specific connection’s ability to initiate payments. TANs are provisioned with an extended time-based validity.

TANs behave differently from standard account numbers in several important ways:

• Detection: You can identify whether a TAN is returned by checking the virtualAccountRoutingPair field in the GET Transaction API response. The real last 4 digits of the account will be provided, if available.
• Institution support: TANs are currently used by select institutions (e.g., Chase and PNC), with others like U.S. Bank expected to follow.
• Limitations: TANs are only valid for ACH and Instant Payment rails. They cannot be used for wires or check processing and may not be supported by all fraud or account verification vendors.
• Routing pairing: Each TAN must be used with the specific routing number provided. Mismatched routing numbers, even from the same bank, can cause failures.
• UI guidance: Because users don’t recognize TANs, you should always show the real last 4 digits of the account as provided, or if not available, the account number should be masked in end-user interfaces.