In Europe? Go to the EU Docs

Trustly ID

Instantly verify identity information to reduce fraud, minimize manual input, and augment your KYC processes.

Suggest Edits

🚧

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

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