Identity Verification
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 Know Your Customer 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. If your Trustly integration includes the use of the Select Bank Widget in multiple user flows, also be sure to include the appropriate flowType for each scenario.
When defining the establish data in your application simply add the property kycType with a value of 1 and if applicable, add the metadata object with the property flowType and the preconfigured name of the appropriate flow type. For example:
const establishData = {
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"
},
returnUrl: "https://yourapp.com/success/path/return",
cancelUrl: "https://yourapp.com/failed/path/cancel",
notificationUrl: "https://yourapp.com/notifications", //optional
kycType: 1,
metadata: {
flowType: "{flowTypeName}" //provided by Trustly
}
};
class LightboxViewVontroller: UIViewController {
var establishData:Dictionary<AnyHashable,Any> = [:]
override func viewDidLoad() {
super.viewDidLoad()
self.establishData = [
"accessId": ACCESS_ID,
"merchantId" : MERCHANT_ID,
"description" : "An example description of a transaction",
"merchantReference" : "unique_transaction_reference_001",
"amount": "0.00",
"paymentType":"Deferred",
"currency":"USD",
"kycType": 1,
"metadata.flowType":FLOW_TYPE_NAME,
"notificationUrl": YOUR_EVENT_LISTENER_URL
]
}
}
With these properties in place, 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 or notificationUrl included in the establishData. If none is included, this event will be sent to the url registered with your merchant ID during initial configuration.
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 - Get user 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": {
"name": "Robert Allen Brown",
"address": [
{
"address1": "567 Cedar St",
"city": "Denver",
"state": "Colorado",
"zip": "80201",
"country": "United States"
}
],
"phone": [
"+1 210-987-6543"
],
"email": [
"[email protected]"
],
"dateOfBirth": "1989-12-21",
"taxId": "301456789",
"driverLicense": {
"number": "124ABC",
"state": "CA"
},
"eligible": true
}
}
User Verification Details
After retrieving the user data from the endpoint above, it may be helpful or necessary to retrieve details regarding the verification, particularly if the user returned is shown as "eligible": false. In order to retrieve additional data regarding eligibility and verification, use the Get user verification details data endpoint listed below:
GET https://sandbox.trustly.one/api/v1/transactions/:id/user/detail
If a valid and authorized transactionID is used with this request, the response will contain a detail object which includes a verification array and an attribute array 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 an abbreviated example response object below:
{
"detail": {
"verification": [
{
"verificationName": "Basic Verification v1",
"result": 3
},
{
"verificationName": "Full Verification NJ v2",
"result": 3
}
],
"attribute": [
{
"name": "name",
"source": "Bank of Trustly",
"sourceType": 1,
"createdAt": 1705516187371,
"verification": [
{
"trustedEntity": "External Service #1",
"verificationType": 4,
"verificationMethod": 1,
"result": 3,
"verifiedAt": 1705516186882
}
]
},
{
"name": "email",
"source": "Bank of Trustly",
"sourceType": 1,
"createdAt": 1705516187348,
"verification": [
{
"trustedEntity": "External Service #1",
"verificationType": 5,
"verificationMethod": 1,
"result": 3,
"verifiedAt": 1705516176223
}
]
},
{
"name": "phone",
"source": "Bank of Trustly",
"sourceType": 1,
"createdAt": 1705516187358,
"verification": [
{
"trustedEntity": "External Service #1",
"verificationType": 4,
"verificationMethod": 1,
"result": 3,
"verifiedAt": 1705516186882
}
]
},
{
"name": "address",
"source": "Bank of Trustly",
"sourceType": 1,
"createdAt": 1705516187364,
"verification": [
{
"trustedEntity": "External Service #1",
"verificationType": 4,
"verificationMethod": 1,
"result": 3,
"verifiedAt": 1705516186882
}
]
}
]
}
}
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, status 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:
POST https://sandbox.trustly.one/api/v1/transactions/:id/feedback
"Registered" feedback request body:
{
"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.
"Void" feedback request body:
{
"status": 13,
"subStatus": 558,
"description": "Known bad user"
}
Event Notifications
In addition to the standard event notifications posted to your notificationUrl during a standard Authorization, Trustly ID verification transactions will trigger the following additional events.
Data Retrieved
Receipt of this event indicates that identity data has successfully been returned from at least one provider. Making requests to the Get User or Get User verification details APIs prior to receiving this event will result in a 400 response. After an event of this type is returned the user object will be available, however the identity verification process may not be complete therefore it is recommended to wait for the Identity Verified event before requesting user data.
{
"merchantId": YOUR_MERCHANT_ID,
"merchantReference": YOUR_TRANSACTION_REFERENCE,
"eventType": "IdentityVerificationDataRetrieved",
"eventId": "1030004388",
"paymentType": "2",
"transactionType": "1",
"objectId": "1025147805",
"objectType": "Transaction",
"message": "performKycVerification",
"timeZone": "Etc/UTC",
"createdAt": "1709932656898",,
"Provider Report Status": "SUCCESS",
"Provider Service Name": "ComprehensiveADL",
"Provider used for validation": "LEXIS_NEXIS"
}
Multiple events may occur
If multiple verifications or providers are configured for your application, an event of this type will be returned for each provider which could result in more than one incoming event of this type.
Identity Verified
Upon receipt of the CustomerIdentityVerified event, the verification process is complete. Regardless of the outcome indicated by the Identity Verified or KYC Result properties, the Get User and Get User Verification Details API endpoints will now return valid user and identity verification data.
{
"merchantId": YOUR_MERCHANT_ID,
"merchantReference": YOUR_TRANSACTION_REFERENCE,
"eventType": "CustomerIdentityVerified",
"eventId": "1030004390",
"paymentType": "2",
"transactionType": "1",
"objectId": "1025147805",
"objectType": "Transaction",
"message": "performKycVerification",
"timeZone": "Etc/UTC",
"createdAt": "1709932657224",
"Identity Verified": "FINISHED",
"KYC Result": "FINISHED"
}
Testing
In order to test real-world scenarios it can be useful to simulate various user identity profiles and outcomes. Simulating outcomes in the Trustly sandbox environment can be done easily using the provided Demo Banks outlined in our Testing guide and the user password triggers listed here.
General Cases
To test a simple happy-path Trustly ID experience simply select the Demo Bank from the Trustly UI and enter the password TrustlyId. This will simulate an eligible user with successfully verified identity data.
Alternatively, entering any random string in the password field will trigger an excess data scenario where the user must manually verify or input some details. The result of this flow will still simulate an eligible user with successfully verified identity data.
Additional Cases
To test more specific simulations, the Demo Bank user interface provides a list of other useful outcomes that may be simulated. To trigger this menu enter the password TrustlyId:help at login.
Summary
The Trustly ID APIs provide a simple and powerful tool for performing Identity Verification and 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/detail API endpoints during onboarding and a secure payment method can be immediately placed on file with the user’s account.
Updated 11 months ago