The establishData object is passed to the selectBankWidget or establish functions and is used to initialize the Bank Authorization for further processing.

Request Parameters

Example Establish Data Object

{
  "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"
}

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.'
driverLicense	Object	-	User's Drivers License number. See Driver License Object.
vip	String	-	VIP status or tier. See VIP tiers for more information.
address	Object	True	Address object representing the User's address.
phone	String	*	User's phone number in ITU E.164 format (ie, `+14155551212`). Required if `channel` contains `sms`.
email	String	*	User's email address. Required if `channel` contains `email`.
balance	String	-	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. Valid options are: - `continue` displays 'Continue' (Default) - `deposit` displays 'Deposit' - `withdraw` displays 'Withdraw' - `pay` displays 'Pay Now'
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.

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