Account Data Retrieval
Trustly provides a solution that allows a user to sign into their Online Banking account and allow the selected ABA Routing and Account Number to be retrieved by the merchant. The merchant can then use this data in their own tokenization and processing platform.
Account ownership verification can be done using Trustlyโs client-side SDK to establish a new transaction then using the authorized transaction to call the Get Account Balance API. In addition, optionally call the Get User API to retrieve the user's personally identifiable information (PII) and verify account ownership against your own data.

Overview
Integrate the Trustly UI
As with most Trustly API flows, retrieving account data begins with acquiring a "Bank Authorization" from a user through an integration with the client-side of your application. For more details on client-side integration see the Trustly UI Guide.
- In your website or mobile application, present the user to sign into Online Banking.
- The Trustly Lightbox opens. The user selects their bank from the list, authenticates, and selects their account.
- When the user selects their account, they will be returned to your
returnUrl
where you can collect the details of the successful Bank Authorization.

After successfully acquiring a Bank Authorization, the primary steps for retrieving account data are highlighted below:
- From your back end, execute the Get Account Balance to retrieve the users bank account and routing information.
- Optionally use the Get User to retrieve the users PII (name, address, phone number, email address) to optionally compare the information provided by the users bank account to information previously provided. You can also optionally use this data to pre-fill information required by your user.
- Continue processing as needed.
Retrieve Bank Details or User PII from Trustly
With a valid Bank Authorization, you can use the Trustly Get Transaction API to retrieve information about the Users bank account that can be displayed in their account on your system. You can also use the Trustly Get User API to retrieve personal information (name, address, email, etc) that can be used to pre-fill fields on your flow or verify information you have already collected from the User.
Use Get Account Balance to retrieve Bank information
Calling the Get User API allows you to get the banking information selected for a given transaction. You call the Get User API by executing a GET
request to the Get Transaction endpoint Get Transaction endpoint, where {transactionId}
is the Bank Account Authorization transaction id. Please refer to the Get Account Balance definition in the API Reference for more information.
Example Get Account Balance API request
https://sandbox.trustly.com/api/v1/transactions/1002810549/payment/paymentProvider/account/balance
The Get Account Balance call returns a JSON response with Bank Account data that you can use in your application. Relevant fields from the response include:
accountBalance.account.providerId
: Trustly Identifier for the Bank selected. You can use this identifier to display the Bank logo to the User.accountBalance.account.nameOnAccount
: Users name that is provided by the selected account.accountBalance.account.name
: Name (friendly identifier) of the Users Bank Account.accountBalance.account.type
: Type of Account selected (Checking or Savings).accountBalance.account.accountNumber
: Bank Account Number provided by the selected account.accountBalance.account.iban
: IBAN provided by the selected account.accountBalance.account.routingNumber
: Bank Routing Number provided by the selected account. RTN on U.S and Sort Code on Europe.
You can then use this information to display the selected Payment Method to your user and use the provided Account and Routing number in your application.
Example Get Transaction response (abbreviated)
{
"accountBalance": {
"account": {
"providerId": "200005501",
"paymentProvider": {
"paymentProviderId": "200005501"
},
"nameOnAccount": "John Smith",
"name": "Demo Checking Account",
"type": 1,
"profile": 1,
"accountNumber": "123456576",
"routingNumber": "124003116",
"verified": true,
"verification": {
"verified": true,
"type": 2,
"hasEnoughFunds": true,
"verificationDate": 1561162678111
}
}
}
}
Please refer to the Get Account Balance definition in the API Reference for more information.
Use Get User Information to retrieve, validate, and display User information
Calling the Get User API allows you to get the personal information (Account Owner name, address, phone, and email) of the User from their selected Bank Account. You call the Get User API by executing a GET
request to the Get Transaction endpoint, where {transactionId}
is the Bank Account Authorization transaction id.
Example Get User request
https://sandbox.trustly.com/api/v1/transactions/1002548448/payment/paymentProvider/user
The Get User call returns a JSON response with User data that you can use in your application. Relevant fields from the response include:
name
: Name(s) associated with the Users Bank Account.address
: Address(es) associated with the Users Bank Account.phone
: Phone Number(s) associated with the Users Bank Account.email
: Email Address(es) associated with the Users Bank Account.
You can then use this information to pre-fill or display the Users information in your flow. You can also use this information to validate the personal information the User may have previously provided in your flow.
Example Get User response (abbreviated)
{
"user": {
"name": [
"John Smith",
"Mary Smith"
],
"address": [
{
"address1": "2000 Broadway Street",
"address2": "",
"city": "Redwood City",
"state": "CA",
"zip": "94063",
"country": "US"
},
{
"address1": "105 Alternate1 Street",
"address2": "#401",
"city": "Redmond",
"state": "WA",
"zip": "98052",
"country": "US"
},
],
"phone": [
"2145553434"
],
"email": [
"[email protected]"
],
}
}
Please refer to the Get User definition in the API Reference for more information.
Use Get Account Summary to retrieve a userโs aggregated financial information
Calling the Get Account Summary API allows you to get the aggregated financial information of a Userโs account(s) (Balance, Deposits, Withdrawals, Overdrafts, NSFs (non-sufficient funds), and NSF fees for periods of 7, 30, and 90 days).
Example Get Account Summary request
https://sandbox.trustly.one/api/v1/transactions/:transactionId/accountSummary
The Get Account Summary API returns a JSON response with three top level properties:
customerId
(string): Trustly identifier for the customer record.lastUpdated
(integer): Epoch timestamp for when the account summary was last aggregated.summary
(array): List of accounts, and relevant summary data, associated with the customer.
Example Get Account Summary response (abbreviated)
{
"customerId": "780001",
"lastUpdated": 1633471332000,
"summary": [
{
"selectedAccount": true,
"currency": "USD",
"nameOnAccount": "John Doe",
"accountNumber": "67675545",
"routingNumber": "557787",
"aggregations": [
{
"days": 7,
"activityEarliestDate": 1631750403554,
"activityLatestDate": 1632268808707,
"balanceMax": "10320.32",
"balanceMin": "9700.10",
"balanceAvg": "9860.13",
"depositCount": 2,
"depositAmountTotal": "620.22",
"depositAmountMax": "500.00",
"withdrawalCount": 1,
"withdrawalAmountTotal": "299.90",
"withdrawalAmountMax": "299.90",
"overdraftCount": 0,
"overdraftAmountTotal": "0.00",
"nsfCount": 0,
"nsfFeeAmountTotal": "0.00"
},
{
"days": 30,
...
},
{
"days": 90,
...
}
]
}
]
}
Adding support for Micro Challenge Deposits (MCD)
If your account has been enabled to process Micro Challenge Deposit (MCD) verification requests, there is an additional step you must take to finish the verification process.
Create the initial bank authorization
The initial bank authorization does not change. You pass in the same establishData
object as usual.
var establishData = {
accessId: {accessId},
requestSignature: {requestSignature},
merchantId: {merchantId},
transactionId: {transactionId},
merchantReference: 'merchant reference',
paymentType: 'Retrieval',
returnUrl: 'https://merchant.com/trustly/return',
cancelUrl: 'https://merchant.com/trustly/cancel'
};
Warning
Do not pass Consumer PII (name, email address, etc) in the
description
field. You can pass Consumer PII in thecustomer
object.
Note
Ensure you're securing your call by including the
requestSignature
parameter.


Handle the redirect
Once you get a successful redirect to your returnUrl
, confirm if the user needs to continue the verification process. Ensure the payment.paymentProvider.type
value is 2
(Manual Entry), the status
is 2
(Authorized), and the payment.account.verified
is false
. Because the payment.paymentProvider.type
is 2
(Manual Entry) and the payment.account.verified
value is false
, message to the user to return to your site when they are ready to verify their account.
Retrieving the test verification code
You can use our Sandbox Merchant Portal to view the test account verification deposit code that was generated for the Bank Authorization.
1. After signing into the Sandbox Merchant Portal, find the Bank Authorization transaction your created earlier.
2. Click on the Transaction ID to bring up the details. Scroll down to the 'Account Verification Deposits' section. Copy the 'Reference Code' value.
Initiate the verification flow
The following examples are using the JavaScript SDK
1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId}
with the Access Id provided to you by Trustly):
<script src="https://sandbox.trustly.com/start/scripts/trustly.js?accessId={accessId}"> </script>
2. To provide optional Trustly configuration options, create a TrustlyOptions
object:
var TrustlyOptions = {
closeButton: false,
dragAndDrop: false,
widgetContainerId: "widget-container-id" //Page element container for the widget
};
For details on the Trustly configuration options, refer to the SDK Specification.
3. To provide the transaction details to the SDK, create an establishData
object:
var establishData = {
accessId: {accessId},
requestSignature: {requestSignature},
merchantId: {merchantId},
transactionId: {transactionId},
merchantReference: 'merchant reference',
paymentType: 'Retrieval',
returnUrl: 'https://merchant.com/trustly/return',
cancelUrl: 'https://merchant.com/trustly/cancel'
};
Warning
Do not pass Consumer PII (name, email address, etc) in the
description
field. You can pass Consumer PII in thecustomer
object.
Tip
Ensure you're securing your call by including the
requestSignature
parameter.
4. Finally, call the Trustly SDK's establish
function:
Trustly.establish(establishData, TrustlyOptions);
The following is a full HTML page using the above example.
Info
You'll want to replace
{accessId}
and{merchantId}
with the values provided to you by Trustly
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script>
var TrustlyOptions = {
closeButton: false,
dragAndDrop: true,
widgetContainerId: 'widget',
};
</script>
<script src="https://sandbox.trustly.com/start/scripts/trustly.js?accessId={accessId}"></script>
</head>
<body style="margin: 0;">
<div id="widget"></div>
</body>
<script>
var establishData = {
accessId: {accessId},
requestSignature: {requestSignature},
merchantId: {merchantId},
transactionId: {transactionId},
merchantReference: 'merchant reference',
paymentType: 'Retrieval',
returnUrl: 'https://merchant.com/trustly/return',
cancelUrl: 'https://merchant.com/trustly/cancel'
};
Trustly.establish(establishData, TrustlyOptions);
</script>
</html>
Enter the test verification code
Using the verification HTML you created above, launch the Trustly Lightbox.

After entering the code retrieved from the Sandbox Merchant Portal and clicking OK, the user is directed back to your site.
Handle the redirect
Once you get a successful redirect to your returnUrl
, confirm if the user is indeed verified. Ensure the payment.paymentProvider.type
value is 2
(Manual Entry), the status
is 2
(Authorized), and the payment.account.verified
is true
. If payment.account.verified
is true
, the account is verified.
Testing
Trustly offers a Demo Bank in the Sandbox environment that can be used to trigger a number of testing scenarios. Read more in Testing.
Error Handling
Trustly uses conventional HTTP response codes to indicate success or failure of an API request.
HTTP Status Code | Description |
---|---|
200 OK | Everything worked as expected. |
400 Bad Request | Often due to a missing, required parameter. |
401 Unauthorized | Invalid accessId or accessKey. |
500 Server error | Something went wrong on Trustly's end. |
503 Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or server maintenance. |
Not all errors map cleanly onto HTTP response codes, however. In addition to the HTTP response code, Trustly returns an array of error objects that describes the errors as a JSON string such as the example below.
{
"errors": [
{
"domain" : "com.trustly.merchantgateway.v1.exception.InvalidParameterException",
"code" : 200,
"message" : "Could not find a transaction using Id 10000021"
}
]
}
Error Code | Description |
---|---|
100 | Internal error. An internal error (an internal database exception for example) occurred when trying to process the request. |
150 | Remote error. A remote error (the consumer's bank interface is down) occurred when trying to process the request. This is an internal error. |
200 | Invalid parameter error. One of the request parameters is invalid (sending an invalid amount format string for example). |
300 | Security error. These are generic security errors that can happen when trying to process the request. |
326 | Expired split token. |
330 | Invalid account. |
331 | Not enough balance. |
375 | Access control error. These occurs when some security parameter (accessId, accessKey or requestSignature) is invalid and the request cannot be processed. |
390 | Fraud analysis. Suspicious transaction or negative data. |
Further Reading
Updated 10 days ago