> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://amer.developers.trustly.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # Verify identity with Trustly ID Trustly ID verifies a new user’s identity at the time of registration, and provides the data required to support the following compliance checks: * Know Your Customer (KYC) * Enhanced Customer Due Diligence (eCDD) * Customer Identification Program (CIP) Trustly ID simplifies the user registration process by leveraging bank-verified Personally Identifiable Information (PII). Instead of requiring users to manually complete long forms, you can use the Trustly UI to authenticate them using their bank credentials. During authentication, Trustly verifies the user's identity in the background and screens them against the Office of Foreign Assets Control (OFAC), Specially Designated Nationals (SDN), Adverse Media, and Politically Exposed Persons (PEP) lists. You then receive this verified data through the Trustly API to pre-fill your registration forms. 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](/api-reference) * **Client-side SDK:** You must integrate the JavaScript SDK (Web) or Mobile SDK to launch the Trustly UI. See [Integrate the Client-Side SDK](/integrate/get-started/quickstart). ## 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](/integrate/core-concepts/the-establish-data-object) 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: ```javascript 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 } }; ``` ```swift class LightboxViewController: UIViewController { var establishData:Dictionary = [:] 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 `returnUrl`and sends a "Success" event to your [webhook listener](/integrate/core-concepts/webhooks-and-events) 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 `transactionID`in 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](/api-reference/api/identity/get-trustly-id-user-data) 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: ```json GET https://sandbox.trustly.one/api/v1/transactions/{transactionId}/user ``` ### Example response The following is an example of the response to the `GET user` request. ```json { "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": [ "robert.brown@example.com" ], "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/{transactionId}/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. For example, `email`, `address` `DOB` and so on, a `verified` boolean property, and a `verification` array that describes how the properties were verified. For example: ```json { "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: ```http POST https://sandbox.trustly.one/api/v1/transactions/{transactionId}/feedback ``` The following table lists the codes you must provide to Trustly in the `POST` request to the Transaction Feedback endpoint. | Response | 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: ```json { "status": 4, "subStatus": 559, "description": "Registered" } ``` The following is an example of the `Void` feedback request body: ```json { "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](/integrate/core-concepts/webhooks-and-events). ### Data retrieved The `CustomerIdentityVerified` event indicates that identity data has successfully returned from at least one provider. Wait for the `CustomerIdentityVerified` event before requesting user data, as the identity verification process may not be complete. Making requests to the [Get User](/api-reference/api/identity/get-trustly-id-user-data) or [Get User verification details](/api-reference/api/identity/get-trustly-id-user-details) APIs prior to receiving this event results in a `400` response. ```json { "merchantId": YOUR_MERCHANT_ID, "merchantReference": YOUR_TRANSACTION_REFERENCE, "eventType": "CustomerIdentityVerified", "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](/api-reference/api/identity/get-trustly-id-user-data) and [Get User Verification Details](/api-reference/api/identity/get-trustly-id-user-details) API endpoints now return valid user and identity verification data. ```json { "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](/integrate/api-fundamentals/testing) and the password triggers listed here to simulate outcomes in the Trustly [sandbox environment](/integrate/get-started/overview-and-solutions). ### 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.