Trustly released some features and APIs described here under the 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.

Trustly ID streamlines the user registration process by verifying a new user’s identity and providing data to support Know Your Customer (KYC) procedures at the time of registration.

Trustly ID lets you use the Trustly UI to guide users through the bank login process instead of forcing them to fill out dozens of fields on multiple pages before you verify the manually entered data. With Trustly ID, you verify a user's identity in the background, and then use Trustly APIs to retrieve the verified user data and complete the registration.

Use the information provided here to learn how to use the Trustly UI to create a new authorization transaction, retrieve verified user data with Trustly APIs, and acknowledge or void the newly created user.

Prerequisites

Trustly API credentials
Trustly UI integration to complete a Bank Authorization

Create an authorization with the Trustly UI

Using the appropriate Trustly UI SDK for your application, render the Select Bank Widget or Lightbox by passing an Establish Data Object API to the chosen method.

To initiate the Trustly ID workflow, define the establishData object in your application by adding the property kycType with a value of 1. If your integration uses specific user flows, also include the flowType property within the metadata object. 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
        ]
  }
}

User experience variations

With these properties in place, the user experiences a slight variation of the standard Trustly UI, including identity verification status messages.

In cases where an initial verification process was incomplete, the user is 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 redirects to the cancel url provided in the establishData object.

Callbacks

After a successful authorization, Trustly redirects to the returnUrland sends a "Success" event to your webhook listener or notificationUrl. If you're not using a webhook listener or you haven't specified a notificationUrl, this event is sent to the URL you registered with your merchant ID during initial configuration.

You use the transactionIDin either of these payloads to retrieve user data. If the user closes the UI or an error occurs, Trustly redirects to the cancelUrl.

Retrieve user data

After a successful authorization, the transactionID allows you to call any of the Transactions-related APIs used to create payments or deposits and retrieve basic account and user data.. For identity verification, the kycType property grants access to the Trustly ID - Get user endpoint.

Retrieve the verified user profile

Use the authorized transactionID to request the user's basic data by executing a GET request to the endpoint. For example:

GET https://sandbox.trustly.one/api/v1/transactions/:id/user

Example response

The following is an example of the response to the GET user request.

{
  "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
  }
}

Check user eligibility and verification status

If the user is shown as"eligible": false , or if you require granular detail for compliance, execute a GET request to the endpoint to retrieve the verification details. For example:

GET https://sandbox.trustly.one/api/v1/transactions/:id/user/detail

Example response (abbreviated)

When a valid and authorized transactionID is used with this request, the response includes a detail object which includes a verification array and an attribute array associated with the user’s identity.

Each attribute object contains a name property which refers to the name of the attribute. Foe example, email, address DOB and so on, a verified boolean property, and a verification array that describes how the properties were verified. For example:

{
  "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 a user

To finalize the user onboarding process, execute a POST request to the endpoint to provide Trustly with the user's status. Status feedback must be provided to acknowledge the user record (if successful) or avoid additional costs (if unsuccessful). For example:

POST https://sandbox.trustly.one/api/v1/transactions/:id/feedback

The following table lists the codes you must provide to Trustly in the POST request to the Transaction Feedback endpoint.

Respnse	Status Code	SubStatus Code	Description	Rationale
Acknowledge (Register)	`4`	`559`	`"Registered"`	The user successfully completed registration. This maintains the transaction validity for future API use.
Void	`13`	`558`	`"Known bad user"`	The registration was not successful. You must void the user if the `transaction ID` is not used, otherwise Trustly assumes the user is active for a given period and additional costs may be incurred.

Example feedback request bodies

The following is an example of the Registered feedback request body:

{
  "status": 4,
  "subStatus": 559,
  "description": "Registered"
}

The following is an example of the Void feedback request body:

{
  "status": 13,
  "subStatus": 558,
  "description": "Known bad user"
}

Event notifications

Trustly ID verification transactions trigger the data retrieved and identity verified events and they are posted to your notificationUrl with the standard event notifications.

Data retrieved

The IdentityVerificationDataRetrieved event indicates that identity data has successfully returned from at least one provider.

Do not call the user data APIs yet. Wait for the CustomerIdentityVerified event before requesting user data, as the identity verification process may not be complete.

Making requests to the Get User or Get User verification details APIs prior to receiving this event results in a 400 response.

{
    "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"
}

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

Receipt of the CustomerIdentityVerified event signals that 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 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

Simulating various user identity profiles and outcomes is essential for testing real-world scenarios. Use the provided Demo Banks described in the Testing guide and the password triggers listed here to simulate outcomes in the Trustly sandbox environment.

General cases

Happy Path: To test a simple happy-path Trustly ID experience, select the Demo Bank from the Trustly UI and enter the password TrustlyId. This simulates an eligible user with successfully verified identity data.
Excess Data Scenario: Entering any random string in the password field triggers a scenario where the user must manually verify or input some details. The result of this flow still simulates an eligible user with successfully verified identity data.

Additional cases

The Demo Bank user interface provides a menu of other useful outcomes you can simulate. To trigger this menu, enter the password TrustlyId:help at login.