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": "merchantId",
  "merchantReference": "merchantReference",
  "paymentType": "Deferred",
  "customer": {
    "name": "Joe User",
    "email": "[email protected]",
    "address": {
      "address1": "2000 Broadway St",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063",
      "country": "US"
    }
  }
}
ParameterTypeR/C/ODescription
accessIdStringRYour client application access id. It will be provided to you.
accountObjectCAccount information. Required if paymentType is Verification and a transactionId is not passed. See Account Object.
addressObjectOShipping address of this payment is different from the customer's address. See Address Object.
allowedPaymentProviderTypesArray(String)OUsed to limit payment provider types available in the Trustly Lightbox. Possible values are 1 (Online Banking) and 2 (Manual Electronic Check)
amountStringRThe amount of the transaction. This represents the maximum amount of transactions that can be processed with Authorization. If the amount is 0.00, there will be no upper bound on the transaction. (10 characters with support for 2 decimal places)
authTokenStringCValue is new. Required if paymentType is Verification and transactionId is passed.
cancelUrlStringRThe gateway redirects the customer browser to this URL if the customer cancels payment (must be a valid URL or function).
currencyStringR3-letter ISO Currency Code. Currently, only USD is supported.
customerObjectRCustomer of this payment. If the customer is already created you can send only the customerId attribute inside the customer object. See Customer Object.
descriptionStringRA summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.
displayAmountStringOIf 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.
merchantIdStringRYour Trustly Merchant Id. It will be provided to you.
merchantReferenceStringRA unique identifier that you create to represent the Transaction in the Trustly system.
metadataObjectOUsed to customize components of the Trustly Lightbox. See MetaData Object.
returnUrlStringRThe gateway redirects the customer browser to this URL if the customer authorizes payment (must be a valid URL or function).
paymentTypeStringRSpecifies the type of transaction to create. Possible values are Deferred, Disbursement, Recurring, Verification, and Retrieval.
recurrenceObjectCConfiguration for recurring payments. Required if paymentType is Recurring. See Recurrence Object.
requestSignatureStringRRequest Signature used to secure the request. See Securing Requests for more information.
transactionIdStringCPrevious transactionId that needs to be verified (split token refresh or MCD flows). Required if paymentType is Verification and you need to refresh a split token.
verificationObjectOUsed 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.

ParameterTypeR/C/ODescription
frequencyUnitNumberRUnit that defines the frequency of payments based on the Frequency Unit Type.
frequencyUnitTypeNumberRCode that defines the frequency unit type (1: day, 2:week, 3: month, 4: year)
recurringAmountStringRPayment amount for each scheduled payment. (10 characters with support for 2 decimal places)
automaticCaptureBooleanRSpecifies 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 TimestampOStart date of the recurring payment. If not specified, the date of the authorization will be the start date.
endDateUnix TimestampOEnd date of the recurring payment. If not specified, the recurring payment will be made according to the schedule until the authorization is canceled.
frequencyNumberOUnit that defines how many payments should be made per Frequency Unit. Defaults to 1.

Account Object

ParameterTypeR/C/ODescription
accountNumberStringRBank Account Number.
routingNumberStringRBank Routing Number.
typeNumberRFinancial Institution Account Type.

Customer Object

ParameterTypeR/C/ODescription
externalIdStringRYour external identifier for the Customer.
nameStringRUser's full name.
taxIdStringCUser's Social Security Number. Required if you are a cryptocurrency or gaming merchant.
driverLicenseObjectOUser's Drivers License number. See Driver License Object.
vipStringOCustomers VIP status. Contact Trustly to understand what values can be provided.
addressObjectRAddress object representing the User's address.
phoneStringCUser's phone number in ITU E.164 format (ie, +14155551212). Required if channel contains sms.
emailStringCUser's email address. Required if channel contains email.
balanceStringOUser's current balance in your system. (10 characters with support for 2 decimal places)
currencyStringO3-character ISO Currency Code of the User's balance.
enrollDateUnix TimestampRDate 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.
dateOfBirthStringCUser's date of birth (i.e. '1965-01-23'). Required if you are a gaming merchant

Driver License Object

ParameterTypeR/C/ODescription
numberStringRUser's Drivers License number.
stateStringR2-character ISO State code where the User's Drivers License was issued.

Address Object

ParameterTypeR/C/ODescription
zipStringRAddress zip (5 digit US Zip Code).
address1StringRAddress Line 1.
address2StringOAddress Line 2.
cityStringRAddress City.
stateStringRAddress State (2 character ISO code).
countryStringRAddress Country (ISO 3166 Country Code).

Verification Object

ParameterTypeR/C/ODescription
verifyCustomerBooleanRIf 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

ParameterTypeR/C/ODescription
langStringOConfigures 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.
finishButtonLabelTypeStringODynamically changes the final button in the Lightbox based on the specified value. Currently deposit (displays 'Deposit') and withdraw (displays 'Withdraw') are supported.

Did this page help you?