Tokenization

Trustly offers a complete solution to handle legacy ACH ABA Routing Number and Account Number data that exists in your database to meet the new NACHA requirements for account tokenization and verification.

Account tokenization and verification can be done with the Trustly Tokenize API or with batch files.

  1. Collect the customer's Account and Routing Number in your flow. Pass this information to Trustly via API or batch file.
  2. Trustly tokenizes the account information. Account Tokens are unique per merchant per account.
  3. If you pass the optional verifyAccount flag with a value of true, Trustly will also verify the account using our own database or a third-party service provided by TeleCheck.
  4. Trustly returns the token and optional verification data to you via API response or batch file.
  5. Update your records with the token and continue processing the transaction.

To initiate the request, pass in the following inputs:

  • merchantId: A unique Trustly merchant identifier.
  • account.accountNumber: This is the account number entered by the sender.
  • account.routingNumber: This is the routing number entered by the sender.

You can optionally pass in more information to the request. For a full list of fields, consult the tokenize API reference.

The processing response echos back the information submitted and add the following fields:

  • token: The Account Token
  • verification.verfied: true if the account is verified; false otherwise.
  • verification.type: Always 3 (Database) for this type of verification.
  • verification.score: A score between 0 and 10. Score definitions can be found in the API Reference.
  • verification.thirdPartyScore: If TeleCheck was used as part of the verification, this field will be returned and have a value between 0 and 999. Third-Party Score definitions can be found in the API Reference.
  • verification.verificationDate: The date and time the verification was completed or updated.

API Example

You can access the Trustly via the Tokenize API.

Example Request

This example uses an account number of 123456576, a routing number of 124003116, and requests optional account verification.

POST https://sandbox.trustly.com/api/v1/accounts/tokenize?verifyAccount=true

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

Example Response

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

Testing

The following table lists inputs and expected results that can be used for testing.

Account NumberRouting NumberScoreThird-party ScoreVerifiedError CodeHTTP Status Code
10000000001234567890false200
10000000011234567891false200
10000000021234567892false200
10000000031234567893false200
10000000041234567894false200
10000000051234567895false200
10000000061234567896true200
10000000071234567897true200
10000000081234567898true200
10000000091234567899true200
100000001012345678910true200
100000100012345678900false200
10000011001234567891100false200
10000012001234567892200false200
10000013001234567893300false200
10000014001234567894400false200
10000015001234567895500false200
10000016001234567896600true200
10000017001234567897700true200
10000018001234567898800true200
10000019001234567899900true200
100000199912345678910999true200
1002000000123456789200400
1003000000123456789300401
1003250000123456789325401
1003750000123456789375401
1001000000123456789100500

Error Handling

The following table lists expected errors and suggested actions that are associated with this product. For more information on Error Handling, consult the Errors.

HTTP StatusCodeSuggested Action
400 Bad Request200Check the request parameters and retry the request.
401 Unauthorized300Check your API Credentials and Merchant Id and try the request again.
401 Unauthorized375Check your API Credentials and Merchant Id and try the request again.
500 Server Error100Retry the request and notify Trustly if the issue persists.

Further Reading


Did this page help you?