> 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 full documentation content, see https://amer.developers.trustly.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # Establish Data object The Establish Data object consolidates the merchant credentials, transaction details, and customer data needed to authorize transactions securely and reliably. With a correctly configured Establish Data object, you'll be able to launch the Trustly UI (Lightbox or Select Bank Widget), and allow your customers to authorize payments or share bank data. Once the workflow is complete, you're ready to handle payments or retrieve data with the Trustly APIs. To integrate the JavaScript SDK (Web) or Mobile SDK required to launch the Trustly UI, see [Integrate the client-side SDK](/integrate/get-started/quickstart). ### Usage The `establishData` object is passed to the `selectBankWidget` or `establish` functions and is used to initialize the Bank Authorization for further processing. The primary method for initiating an authorization transaction is through the built-in methods of the Trustly UI libraries: `establish` and `selectBankWidget`. These methods both require the Establish Data as a parameter. ### Parameter reference The Establish Data object includes all required and optional parameters, grouped for clarity. Optional parameters may be required based on the `paymentType` and merchant conditions. | Parameter | Type | Required | Description | | :-------------------------- | :------------ | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accessId | String | True | Your client application **Access ID** (provided by Trustly). | | merchantId | String | True | Your Trustly **Merchant ID** (provided by Trustly). | | requestSignature | String | True | Request Signature used to secure the request. See [Securing Requests](/integrate/api-fundamentals/secure-requests-and-signature-validation) for more information. | | merchantReference | String | True | A unique identifier representing the transaction in your system (e.g., Order number or Payment ID). | | returnUrl | String | True | Redirect URL to be called when a user successfully creates a bank authorization (Success URL). | | cancelUrl | String | True | Redirect URL to be called when a user cancels from the Lightbox or the bank authorization is otherwise unsuccessful (Failure URL). | | paymentType | String | False | Specifies the type of transaction to create. Possible values are `Deferred`, `Disbursement`, `Recurring`, `Verification`, and `Retrieval`. Default value is `Retrieval` if not otherwise provided. | | notificationUrl | String | False | Notification URL for Trustly to send [events/webhooks](/integrate/core-concepts/webhooks-and-events) associated with this transaction. Overrides the default configured URL. | | amount | Float | \* | **Required for `Instant` payments.** For `Deferred` payments, this is an optional limit for future capture transactions (10 character max). | | currency | String | \* | 3-letter ISO Currency Code (e.g., `USD` or `CAD`). Required if `amount` is present. | | description | String | \* | A summary description of the order. **Do not pass Consumer PII** in this field. | | displayAmount | String | False | The amount displayed to the user during the Lightbox experience. This is for display purposes only and has no impact on the actual authorization. | | customer | Object | True | Customer associated with the payment. See **\[Customer Object]**. | | recurrence | Object | \* | Required if `paymentType` is `Recurring`. Configuration options for recurring payments. See **Recurrence Object**. | | metadata | Object | False | Used to customize components of the Trustly Lightbox. See **\[MetaData Object]**. | | allowedPaymentProviderTypes | Array(String) | False | Used to limit payment provider types. Possible values: `1` (Online Banking) and `2` (Manual Electronic Check). | | paymentProviderId | String | False | If provided, the Lightbox opens directly to the FI login page. ID must be retrieved from the [List Payment Providers](/api-reference/api/payment-providers/get-payment-providers) API. | | address | Object | False | Shipping address, required if different from the customer's billing address. See **Address Object**. | | account | Object | False | Account information. Required if `paymentType` is `Verification` and a `transactionId` is not passed. See **Account Object**. | | authToken | String | False | Value is `new`. Required if `paymentType` is `Verification` and `transactionId` is passed. | | transactionId | String | False | Previous `transactionId` that needs to be verified (e.g., split token refresh). Required if `paymentType` is `Verification`. | | verification | Object | False | Used to set parameters for the fraud analysis engine. See **\[Verification Object]**. | > **Note:** Most payment properties (`amount`, `currency`, `description`, `customer`) are required if `paymentType` is set to `Deferred`, `Disbursement`, `Instant`, or `Recurring`. ```json { "merchantId": "YOUR_MERCHANT_ID", "accessId": "YOUR_ACCESS_ID", "requestSignature": "{requestSignature}", "merchantReference": "{unique_merchant_payment_identifier}", "description": "any additional user-friendly descriptive information for the payment", "paymentType": "Deferred", "currency": "USD", "amount": "0.00", "customer": { "name": "Joe User", "email": "joe.user@email.com", "address": { "address1": "2000 Broadway St", "city": "Redwood City", "state": "CA", "zip": "94063", "country": "US" } }, "returnUrl": "https://yourapp.com/path/return", "cancelUrl": "https://yourapp.com/path/cancel" } ``` ### Object definitions The following objects define the nested data structures required for submitting customer details, verification data, and recurrence rules. #### Recurrence object See [Capture Transaction](/api-reference/api/transactions/post-transactions-transaction-id-capture) for more information on Recurring Payments. | Parameter | Type | Required | Description | | :---------------- | :------------- | :------: | :------------------------------------------------------------------------------------------------------------------ | | frequencyUnit | Number | True | Unit that defines the frequency of payments based on the `frequencyUnitType`. | | frequencyUnitType | Number | True | Code that defines the frequency unit type (`1`: day, `2`: week, `3`: month, `4`: year). | | recurringAmount | String | True | Payment amount for each scheduled payment. (10 characters, 2 decimal places max). | | automaticCapture | Boolean | True | Specifies if Trustly automatically processes the payment per schedule, or if a **Capture API** request is required. | | startDate | Unix Timestamp | False | Start date of the recurring payment (defaults to the date of authorization). | | endDate | Unix Timestamp | False | End date of the recurring payment (continues until authorization is canceled if not specified). | | frequency | Number | False | Unit that defines how many payments should be made per Frequency Unit (Defaults to `1`). | #### Account object | Parameter | Type | Required | Description | | :------------ | :----- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountNumber | String | True | Bank Account Number. | | iban | String | False | Standardized account number for global transfers. Conditionally, only use with paymentType verification and don't include an account number and routing number. | | routingNumber | String | True | Bank Routing Number. | | type | Number | True | Financial Institution Account Type. | #### Customer object | Parameter | Type | Required | Description | | :------------ | :------------- | :------: | :--------------------------------------------------------------------------------------------- | | externalId | String | True | Your external identifier for the Customer. | | name | String | True | User's full name. | | address | Object | True | Address object representing the User's address. | | enrollDate | Unix Timestamp | True | Date of the user's first transaction in your system (Unix Timestamp in ms). | | taxId | String | \* | Customer tax ID (for example, SSN, SIN). *May be required depending on industry and location.* | | phone | String | True | User's phone number in ITU E.164 format. | | email | String | True | User's email address. | | dateOfBirth | String | \* | User's date of birth (i.e. '1965-01-23'). | | driverLicense | Object | False | User's Drivers License number. See **\[Driver License Object]**. | | vip | String | False | VIP status or tier. See [VIP tiers](/integrate/manage-your-integration/vip-tiers). | | balance | String | False | User's current balance in your system (10 characters, 2 decimal places max). | | currency | String | False | 3-character ISO Currency Code of the User's balance. | #### Verification object | Parameter | Type | Required | Description | | :------------- | :------ | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | verifyCustomer | Boolean | True | If `true`, Trustly only allows the transaction if the passed customer name and zip code match the data provided by the User's selected Bank Account. | #### Address object | Parameter | Type | Required | Description | | :-------- | :----- | :------: | :--------------------------------------- | | zip | String | True | Address zip (5 digit US Zip Code). | | address1 | String | True | Address Line 1. | | address2 | String | False | Address Line 2. | | city | String | True | Address City. | | state | String | True | Address State (2 character ISO code). | | country | String | True | Address Country (ISO 3166 Country Code). | #### Driver license object | Parameter | Type | Required | Description | | :-------- | :----- | :------: | :---------------------------------------------------------------------- | | number | String | True | User's Drivers License number. | | state | String | True | 2-character ISO State code where the User's Drivers License was issued. | #### Metadata object Additional data used for less common scenarios can be provided in the Metadata object. The `universalLink` and `deepLinkStrategy` parameters are optional if you have already configured default values in the **Admin Console**. Any values provided here will override the defaults. | Parameter | Type | Description | | :-------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lang | String | Configures the Lightbox language (`{ISO 639 Language Code}_{ISO 3166 Country Code}`, e.g., `de_DE`). Defaults to `en_US`. | | flowType | String | Configures the Lightbox to utilize a specific pre-configured user flow. Contact your Trustly point of contact for options. | | finishButtonLabelType | String | Dynamically changes the final button label in the Lightbox. Valid options are: `continue` (Default), `deposit`, `withdraw`, `pay`. | | integrationContext | String | Configures Trustly UI to handle OAuth bank login flows in mobile applications. Accepted values are `InAppBrowser`, `InAppBrowserNotify` and `ExternalBrowser`. See the [OAuth and Mobile apps guide](/integrate/api-fundamentals/authentication-and-oauth). | | urlScheme | String | The URL associated with your mobile application used for redirects on success or failure. See the [OAuth and Mobile apps guide](/integrate/api-fundamentals/authentication-and-oauth). | | universalLink | String | The Universal Link (iOS) or App Link (Android) used to redirect the user back to the merchant's app. | | deepLinkStrategy | String | Specifies the strategy used for deep linking. Accepted values are `url-scheme` or `universal-link`. | | clc | Object | Identifying data for Trustly In-Person transactions. Requires Trustly In-Person configurations. See **CLC Object** | #### CLC object If configured for Trustly In-Person, the CLC object is required. | Parameter | Type | Required | Description | | :---------------- | :----- | :------: | :------------------------------------------------ | | propertyId | String | True | ID number for property or location. | | gamingAssetNumber | String | True | ID number specific to Electronic Wagering System. | | datetimeQR | String | True | Timestamp of QR code generation. | | playerCardNumber | String | False | Player tracking number. |