Establish Data

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.

ParameterTypeRequiredDescription
accessIdStringTrueYour client application access id. It will be provided to you.
accountObject-Account information. Required if paymentType is Verification and a transactionId is not passed. See Account Object.
addressObject-Shipping address of this payment is different from the customer's address. See Address Object.
allowedPaymentProviderTypesArray(String)-Used to limit payment provider types available in the Trustly Lightbox. Possible values are 1 (Online Banking) and 2 (Manual Electronic Check)
amountFloat-An optional limit for future capture transactions. This represents the maximum amount of transactions that can be processed. (10 character max)
authTokenString-Value is new. Required if paymentType is Verification and transactionId is passed.
cancelUrlStringTrueThe gateway redirects the customer browser to this URL if the customer cancels payment (must be a valid URL or function).
currencyStringTrue3-letter ISO Currency Code. Currently, only USD and CAD are supported.
customerObjectTrueCustomer of this payment. If the customer is already created you can send only the customerId attribute inside the customer object. See Customer Object.
descriptionString-A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.
displayAmountString-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.
merchantIdStringTrueYour Trustly Merchant Id. It will be provided to you.
merchantReferenceStringTrueA unique identifier that you create to represent the Transaction in the Trustly system.
metadataObject-Used to customize components of the Trustly Lightbox. See MetaData Object.
notificationUrlString-Notification URL to use for events associated with this transaction. Overrides the default notification URL configured at the merchant level.
returnUrlStringTrueThe gateway redirects the customer browser to this URL if the customer authorizes payment (must be a valid URL or function).
paymentTypeString-Specifies the type of transaction to create. Possible values are Deferred, Disbursement, Recurring, Verification, and Retrieval.
recurrenceObject*Required if paymentType is Recurring. Configuration options for recurring payments. See Recurrence Object.
requestSignatureStringTrueRequest Signature used to secure the request. See Securing Requests for more information.
transactionIdString*Required if paymentType is Verification. Previous transactionId that needs to be verified (split token refresh or MCD flows).
verificationObject-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.

ParameterTypeRequiredDescription
frequencyUnitNumberTrueUnit that defines the frequency of payments based on the Frequency Unit Type.
frequencyUnitTypeNumberTrueCode that defines the frequency unit type (1: day, 2:week, 3: month, 4: year)
recurringAmountStringTruePayment amount for each scheduled payment. (10 characters with support for 2 decimal places)
automaticCaptureBooleanTrueSpecifies 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).
startDateUnix Timestamp-Start date of the recurring payment. If not specified, the date of the authorization will be the start date.
endDateUnix 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.
frequencyNumber-Unit that defines how many payments should be made per Frequency Unit. Defaults to 1.

Account Object

ParameterTypeRequiredDescription
accountNumberStringTrueBank Account Number.
routingNumberStringTrueBank Routing Number.
typeNumberTrueFinancial Institution Account Type.

Customer Object

ParameterTypeRequiredDescription
externalIdStringTrueYour external identifier for the Customer.
nameStringTrueUser's full name.
taxIdString*'Customer tax ID (e.g. SSN (US), SIN (CA)). May be required depending on industry and location.'
driverLicenseObject-User's Drivers License number. See Driver License Object.
vipString-VIP status or tier. See VIP tiers for more information.
addressObjectTrueAddress object representing the User's address.
phoneString*User's phone number in ITU E.164 format (ie, +14155551212). Required if channel contains sms.
emailString*User's email address. Required if channel contains email.
balanceString-User's current balance in your system. (10 characters with support for 2 decimal places)
currencyString-3-character ISO Currency Code of the User's balance.
enrollDateUnix TimestampTrueDate 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.
dateOfBirthString*User's date of birth (i.e. '1965-01-23'). Required for gaming merchants

Driver License Object

ParameterTypeRequiredDescription
numberStringTrueUser's Drivers License number.
stateStringTrue2-character ISO State code where the User's Drivers License was issued.

Address Object

ParameterTypeRequiredDescription
zipStringTrueAddress zip (5 digit US Zip Code).
address1StringTrueAddress Line 1.
address2String-Address Line 2.
cityStringTrueAddress City.
stateStringTrueAddress State (2 character ISO code).
countryStringTrueAddress Country (ISO 3166 Country Code).

Verification Object

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

ParameterTypeRequiredDescription
langStringFalseConfigures 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.
finishButtonLabelTypeStringFalseDynamically changes the final button in the Lightbox based on the specified value. Currently deposit (displays 'Deposit') and withdraw (displays 'Withdraw') are supported.
integrationContextStringFalseConfigures 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.
urlSchemeStringFalseThe 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 .
clcObjectConditionalIdentifying 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.

ParameterTypeRequiredDescription
propertyIdStringTrueID number for property or location
gamingAssetNumberStringTrueID number specific to Electronic Wagering System
datetimeQRStringTrueTimestamp of QR code generation
playerCardNumberStringFalsePlayer tracking number