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.

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.

Parameter	Required/Optional	Description
`merchantId`	Required	Your unique Trustly merchant identifier.
`account.accountNumber`	Required	The account number entered by the sender.
`account.routingNumber`	Required	The routing number entered by the sender.

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

// POST https://{environment}[.trustly.com/api/v1/accounts/tokenize?verifyAccount=true](https://.trustly.com/api/v1/accounts/tokenize?verifyAccount=true)

{
  "merchantId": "1002463580",
  "account": {
    "accountNumber": "123456575",
    "routingNumber": "124003116",
    "type": 1
  }
}

Understand the response

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

Field	Description
`token`	The account token. This is the non-sensitive string you must store for all future payments.
`verification.verified`	`true` if Trustly verified the account; `false` otherwise.
`verification.type`	The verification method used. This is `3` (Database) in this use case.
`verification.score`	A risk score between `0` and `10`.
`verification.thirdPartyScore`	A third-party risk score between `0` and `999`, returned if a third-party service was used for verification.
`verification.verificationDate`	The date and time Trustly completed or updated the verification.

Response example

{
  "account": {
    "type": 1,
    "accountNumber": "123456575",
    "routingNumber": "124003116",
    "verification": {
      "verified": false,
      "type": 3,
      "score": 4,
      "thirdPartyScore": 400,
      "verificationDate": 1556740304129
    },
    "token": "K11612346575"
  }
}

Error and score definitions

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