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.

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 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	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.
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.

1 {
2   "merchantId": "YOUR_MERCHANT_ID",
3   "accessId": "YOUR_ACCESS_ID",
4   "requestSignature": "&#123;requestSignature&#125;",
5   "merchantReference": "&#123;unique_merchant_payment_identifier&#125;",
6   "description": "any additional user-friendly descriptive information for the payment",
7   "paymentType": "Deferred",
8   "currency": "USD",
9   "amount": "0.00",
10   "customer": {
11     "name": "Joe User",
12     "email": "joe.user@email.com",
13     "address": {
14       "address1": "2000 Broadway St",
15       "city": "Redwood City",
16       "state": "CA",
17       "zip": "94063",
18       "country": "US"
19     }
20   },
21   "returnUrl": "https://yourapp.com/path/return",
22   "cancelUrl": "https://yourapp.com/path/cancel"
23 }

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

1	{
2	"merchantId": "YOUR_MERCHANT_ID",
3	"accessId": "YOUR_ACCESS_ID",
4	"requestSignature": "{requestSignature}",
5	"merchantReference": "{unique_merchant_payment_identifier}",
6	"description": "any additional user-friendly descriptive information for the payment",
7	"paymentType": "Deferred",
8	"currency": "USD",
9	"amount": "0.00",
10	"customer": {
11	"name": "Joe User",
12	"email": "joe.user@email.com",
13	"address": {
14	"address1": "2000 Broadway St",
15	"city": "Redwood City",
16	"state": "CA",
17	"zip": "94063",
18	"country": "US"
19	}
20	},
21	"returnUrl": "https://yourapp.com/path/return",
22	"cancelUrl": "https://yourapp.com/path/cancel"
23	}