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.

For more information about how Trustly UI components work, see About Trustly UI.

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.

For more details see the Trustly UI sections on Select Bank Widget or Launch the Lightbox.

Establish API (BETA)

An alternative to the Trustly UI, the Establish API can be used to generate a Trustly-hosted web page where a user can complete an authorization. This approach is useful for early development, testing, and situations where Trustly cannot be integrated into an existing user experience.

Parameter reference

The Establish Data object includes all required and optional parameters, grouped for clarity. Note that optional parameters may become 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 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 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	*	Customer of this payment. Required if payment properties are set. 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.
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.

{
  "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": "[email protected]",
    "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 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 (e.g., SSN, SIN). May be required depending on industry and location.
phone	String	*	User's phone number in ITU E.164 format. Required if `channel` contains `sms`.
email	String	*	User's email address. Required if `channel` contains `email`.
dateOfBirth	String	*	User's date of birth (i.e. '1965-01-23'). Required for gaming merchants.
driverLicense	Object	False	User's Drivers License number. See [Driver License Object].
vip	String	False	VIP status or tier. See 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.

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.
urlScheme	String	The URL associated with your mobile application used for redirects on success or failure. See the OAuth and Mobile apps guide.
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.