The establishData object is passed to the selectBankWidget or establish functions and is used to initialize the Bank Authorization for further processing.
A complete list of parameters can be found below. It is important to note that some optional parameters may be required due to the payment type and merchant conditions. Always consult your account representative when in doubt or experiencing unexpected behavior.
Parameter
Type
Required
Description
accessId
String
True
Your client application access id. It will be provided to you.
account
Object
-
Account information. Required if paymentType is Verification and a transactionId is not passed. See Account Object.
address
Object
-
Shipping address of this payment is different from the customer's address. See Address Object.
allowedPaymentProviderTypes
Array(String)
-
Used to limit payment provider types available in the Trustly Lightbox. Possible values are 1 (Online Banking) and 2 (Manual Electronic Check)
amount
Float
-
An optional limit for future capture transactions. This represents the maximum amount of transactions that can be processed. (10 character max)
authToken
String
-
Value is new. Required if paymentType is Verification and transactionId is passed.
cancelUrl
String
True
The gateway redirects the customer browser to this URL if the customer cancels payment (must be a valid URL or function).
currency
String
True
3-letter ISO Currency Code. Currently, only USD and CAD are supported.
customer
Object
True
Customer of this payment. If the customer is already created you can send only the customerId attribute inside the customer object. See Customer Object.
description
String
-
A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.
displayAmount
String
-
If passed, this amount will be displayed during the Trustly Lightbox experience. This is often used in conjunction with the metadata.finishButtonLabelType field. Please note that this is for display purposes only, it has no impact on the actual bank authorization itself.
merchantId
String
True
Your Trustly Merchant Id. It will be provided to you.
merchantReference
String
True
A unique identifier that you create to represent the Transaction in the Trustly system.
metadata
Object
-
Used to customize components of the Trustly Lightbox. See MetaData Object.
notificationUrl
String
-
Notification URL to use for events associated with this transaction. Overrides the default notification URL configured at the merchant level.
returnUrl
String
True
The gateway redirects the customer browser to this URL if the customer authorizes payment (must be a valid URL or function).
paymentType
String
-
Specifies the type of transaction to create. Possible values are Deferred, Disbursement, Recurring, Verification, and Retrieval.
recurrence
Object
*
Required if paymentType is Recurring. Configuration options for recurring payments. See Recurrence Object.
requestSignature
String
True
Request Signature used to secure the request. See Securing Requests for more information.
transactionId
String
*
Required if paymentType is Verification. Previous transactionId that needs to be verified (split token refresh or MCD flows).
verification
Object
-
Used to set parameters to the fraud analysis engine. See Verification Object.
Do not pass Consumer PII in the `description` field. If you wish to pass Consumer PII, use the `customer` object.
Recurrence Object
See Capture Transaction for more information on using Trustly for Recurring Payments.
Parameter
Type
Required
Description
frequencyUnit
Number
True
Unit that defines the frequency of payments based on the Frequency Unit Type.
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 with support for 2 decimal places)
automaticCapture
Boolean
True
Specifies if this recurring payment will be processed by Trustly automatically per the Recurring schedule, or if a Capture API request will be made (also per the Recurring schedule).
startDate
Unix Timestamp
-
Start date of the recurring payment. If not specified, the date of the authorization will be the start date.
endDate
Unix Timestamp
-
End date of the recurring payment. If not specified, the recurring payment will be made according to the schedule until the authorization is canceled.
frequency
Number
-
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.
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.
taxId
String
*
'Customer tax ID (e.g. SSN (US), SIN (CA)). May be required depending on industry and location.'
User's current balance in your system. (10 characters with support for 2 decimal places)
currency
String
-
3-character ISO Currency Code of the User's balance.
enrollDate
Unix Timestamp
True
Date of the user's first transaction in your system, regardless of payment method used. This should be passed as a Unix Timestamp (epoch) in ms.
dateOfBirth
String
*
User's date of birth (i.e. '1965-01-23'). Required for gaming merchants
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.
Address Object
Parameter
Type
Required
Description
zip
String
True
Address zip (5 digit US Zip Code).
address1
String
True
Address Line 1.
address2
String
-
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).
Verification Object
Parameter
Type
Required
Description
verifyCustomer
Boolean
True
If enabled and set to true, Trustly will only allow the transaction if the passed customer name and zip code match what is provided by the User's selected Bank Account.
Metadata Object
Additional data used for less common scenarios can be provided in the Metadata object.
Parameter
Type
Required
Description
lang
String
False
Configures the Lightbox to be displayed in the specified language. The value should be passed in the format {ISO 639 Language Code}_{ISO 3166 Country Code} (ie, de_DE or fr_CA). Defaults to en_US if not passed.
finishButtonLabelType
String
False
Dynamically changes the final button in the Lightbox based on the specified value. Currently deposit (displays 'Deposit') and withdraw (displays 'Withdraw') are supported.
integrationContext
String
False
Configures Trustly UI to handle OAuth bank login flows in mobile applications. Accepted values are InAppBrowser, InAppBrowserNotify and ExternalBrowser. More details can be found in the OAuth and Mobile apps guide.
urlScheme
String
False
The url associated with your mobile application. When users are directed to an external bank login or application on success or failure they will be redirected to this url. More details can be found in the OAuth and Mobile apps guide .
clc
Object
Conditional
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. Each property's requirement denoted below is only relevant for apps configured for Trustly In-person.