Trustly ID
Instantly verify identity information to reduce fraud, minimize manual input, and augment your KYC processes.
BETA Features Included
This guide refers to features and APIs which have been released under the Trustly Beta program. Standard Trustly Service Level Agreements do not apply to this functionality at this time. Some behaviors, field names, and property types are likely to change prior to the General Availability release.
Overview
Trustly ID is a streamlined user registration process that verifies the identity of a new user and provides data to support KYC procedures at the time of registration. Instead of forcing users to fill out dozens of fields on multiple pages before verifying the manually entered data, use the Trustly UI to guide users through a simple bank login process, verify their identities in the background, and use the Trustly API to retrieve the verified user data to complete the registration.
Prerequisites
- Trustly API credentials
- Trustly UI integration to complete a Bank Authorization
Summary
This guide will cover using the Trustly UI to create a new Authorization Transaction, retrieving verified user data from the Trustly API, and depending on a completed registration, acknowledging or voiding the newly created user.
Create an Authorization with Trustly UI
Using the appropriate Trustly UI SDK for your application, render the Select Bank Widget or Lightbox by passing an Establish Data object to the chosen method.
Simply add the property kycType
with a value of 1
to the establishData
object, as seen below:
{
accessId: "{YOUR_ACCESS_ID}",
merchantId: "{YOUR_MERCHANT_ID}",
requestSignature: "{SERVER_GENERATED_SIGNATURE}",
description: "transaction description",
merchantReference: "merchant reference",
paymentType: "Deferred",
currency: "USD", // or "CAD"
customer: {
externalId: "{YOUR_SYSTEM_CUSTOMER_ID}",
name: "Joe User"
},
kycType: 1,
returnUrl: "https://yourapp.com/success/path/return",
cancelUrl: "https://yourapp.com/failed/path/cancel"
}
With this property set, the user will experience a slight variation of the standard Trustly UI. In most scenarios, the only difference is the presence of identify verification status messages such as the ones below:

In cases where an initial verification process was incomplete and additional user data is required, the user will be presented with a form requesting manual input for the required missing information:

If the user closes the Trustly UI or some other error occurs, Trustly will redirect to the cancel
url provided in the establishData.
After the user has successfully completed the authorization, Trustly will redirect to the return
url and send a “Success” event to the webhook listener included in the establishData (or if none is included, the url registered with your merchant ID.
Note the transactionID
provided in either of these payloads in order to request the user data from the Trustly API in the next step.
Retrieve User Data
After a successful authorization, the transactionID
associated with the transaction can be used to call any of the Transactions-related APIs. These can be used for creating payments, deposits, retrieving basic account data, and retrieving basic user data. In addition to these endpoints, an authorized transaction created with the kycType
property has access to the Trustly ID "know your customer" data endpoint.
Standard User Data
Using an authorized transactionID
with the endpoint below will return various basic user data.
GET https://sandbox.trustly.one/api/v1/transactions/:id/user
An example response object is listed below:
{
"user": {
"id": "1002580963",
"name": "Joe User",
"taxId": "012345678",
"address": [
{
"address1": "2000 Broadway St",
"city": "Redwood City",
"state": "CA",
"zip": "94063",
"country": "US"
}
],
"phone": [
"+16505551212"
],
"email": [
"[email protected]"
],
"createdAt": 1555696836548,
"updatedAt": 1555696836548
}
}
Know Your Customer Data
In addition to the user
endpoint above, an authorized transaction created with the kycType"
property has access to the "know your customer" data endpoint listed below:
GET https://sandbox.trustly.one/api/v1/transactions/:id/user/kyc
If a valid and authorized transactionID
is used with this request, the response will contain a userId
property and an array of attributes
associated with the user’s identity. Each attribute object will contain a name
property which refers to the name of the attribute (e.g. email
, address
DOB
etc.) as well as a verified
boolean property and an array of verifications
which describe how the property was verified. See a limited example response object below:
{
"userId": "1002580963",
"attributes": [
{
"name": "name",
"source": "Bank of America",
"sourceType": 0,
"createdAt": 1643926146423,
"verified": true,
"verifications": [
{
"verificationType": 0,
"veritifcationMethod": 0,
"trustedEntity": "Bank of America",
"verifiedAt": 1643926146423,
"verified": true
},
{
"verificationType": 3,
"veritifcationMethod": 2,
"trustedEntity": "The United States Department of State",
"verifiedAt": 1643926146423,
"verified": true
}
]
},
{
"name": "email",
"source": "Trustly Lightbox",
"sourceType": 1,
"createdAt": 1643926146423,
"verified": true,
"verifications": [
{
"verificationType": 1,
"veritifcationMethod": 3,
"trustedEntity": "gmail.com",
"verifiedAt": 1643926146423,
"verified": true
}
]
}
]
}
This response data can be used to determine a user’s eligibility, reduce fraud and improve the user experience by minimizing the need for manual entry.
Register or Void the User
Depending on the result of the user onboarding process, feedback must be provided to Trustly. If the user successfully completed the registration process, provide a Registered
status to acknowledge the user record and maintain the validity of the associated transaction for usage with other relevant APIs:
curl --request POST \
--url https://sandbox.trustly.one/api/v1/transactions/:id/feedback \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{"feedback": {"status": 4,"subStatus": 559,"description": "Registered"}}
If the registration was not successful, the user record should be voided. If the user is not voided but the associated transactionID
is not used, Trustly will assume the user is active for a given period of time and additional costs may be incurred.
curl --request POST \
--url https://sandbox.trustly.one/api/v1/transactions/:id/feedback \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{"feedback": {"status": 13,"subStatus": 558,"description": "Known bad user"}}
Summary
The Trustly ID APIs provide a simple and powerful tool for performing Know Your Customer (KYC) compliance checks as well as improving user onboarding and reducing fraud. By simply adding the kycType: 1
property to the establishData of an existing Trustly payments integration, verified user identity data can be retrieved from the GET /transactions/:id/user
and GET /transactions/:id/user/kyc
API endpoints during onboarding and a secure payment method can be immediately placed on file with the user’s account.
Updated about 2 months ago