Tokenize bank information

Use tokenization to securely convert your customer’s sensitive Automated Clearing House (ACH) bank information (routing and account numbers) into a unique, non-sensitive token.

This is the recommended approach for storing payment details. Tokenization helps you comply with National Automated Clearing House Association (NACHA) account validation requirements and significantly reduces the need to store sensitive data, lowering your compliance burden.

After Trustly tokenizes an account, you use the resulting token for all future payments and verification checks.

To tokenize an account, you complete the following actions:

• Data collection: Collect the customer’s Account Number and Routing Number in your user interface.
• Data transfer: Pass the sensitive data to the POST /accounts/tokenize endpoint. You can optionally include verifyAccount=true to validate the account simultaneously.
• Account tokenization: Trustly tokenizes the account and performs the requested verification check.
• Token return: Trustly returns a unique account token and any optional verification data in the API response.
• Token storage: Update your records, store the token and discard the raw, sensitive account numbers.

Tokenization workflow

The following table describes the tokenization workflow steps.

Initiate a tokenization request

To initiate a tokenization request, send a POST request to the /accounts/tokenize endpoint with the following required inputs in the request body.

You can optionally pass in more information, such as customer details, or use the query parameter ?verifyAccount=true to perform account validation. For a full list of request fields, see the Tokenize Account API.

Request example

This example requests tokenization and optional verification (?verifyAccount=true).

1
// POST https://{environment}[.trustly.com/api/v1/accounts/tokenize?verifyAccount=true](https://.trustly.com/api/v1/accounts/tokenize?verifyAccount=true)
2
3
{
4
  "merchantId": "1002463580",
5
  "account": {
6
    "accountNumber": "123456575",
7
    "routingNumber": "124003116",
8
    "type": 1
9
  }
10
}

Understand the response

Upon success, Trustly echoes the information submitted and adds the following key fields:

Response example

1
{
2
  "account": {
3
    "type": 1,
4
    "accountNumber": "123456575",
5
    "routingNumber": "124003116",
6
    "verification": {
7
      "verified": false,
8
      "type": 3,
9
      "score": 4,
10
      "thirdPartyScore": 400,
11
      "verificationDate": 1556740304129
12
    },
13
    "token": "K11612346575"
14
  }
15
}

Error and score definitions

See the Status Codes Reference for score definitions (FCRA and Non-FCRA) and API status and error codes.