Token Authority

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.

Summary

Account tokenization and verification can be done using Trustly’s Tokenize an Account to validate and or tokenize the existing merchant’s database. The primary steps of this tutorial are:

  1. Collect the customers Account and Routing Number in your user interface. Pass this information to Trustly's Tokenize API endpoint.
  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.

Tokenize API Endpoint

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.

Example Request

In this example, we use an account number of 123456576 and a routing number of 124003116. We are also requesting optional account verification and passing in optional customer information.

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

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

Responses

As part of the response data, Trustly will echo 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: Will always be 3 (Database) in this use case.
  • verification.score: This will be 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 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.

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 CodeScore Type
10000000001240031160false200Non Telecheck
10000000011240031161false200Non Telecheck
10000000021240031162false200Non Telecheck
10000000031240031163false200Non Telecheck
10000000041240031164false200Non Telecheck
10000000051240031165false200Non Telecheck
10000000061240031166true200Non Telecheck
10000000071240031167true200Non Telecheck
10000000081240031168true200Non Telecheck
10000000091240031169true200Non Telecheck
100000001012400311610true200Non Telecheck
100000100012400311600false200FCRA
10000011001240031161100false200FCRA
10000012001240031162200false200FCRA
10000013001240031163300false200FCRA
10000014001240031164400false200FCRA
10000015001240031165500false200FCRA
10000016001240031166600true200FCRA
10000017001240031167700true200FCRA
10000018001240031168800true200FCRA
10000019001240031169900true200FCRA
100000199912400311610999true200FCRA
100000100012400311600false200Non-FCRA
1000001015124003116115false200Non-FCRA
1000001020124003116120false200Non-FCRA
1000001025124003116125false200Non-FCRA
1000001035124003116135true200Non-FCRA
1000001045124003116145true200Non-FCRA
1002000000124003116200400
1003000000124003116300401
1003250000124003116325401
1003750000124003116375401
1001000000124003116100500

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