Establish Data
The Establish Data object is your gateway to kicking off bank authorization flows with Trustly. It’s the key structure that consolidates all the essential information—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) giving users a simple way to authorize payments or share bank data. Once the flow is complete, you're ready to handle payments or retrieve data through Trustly’s APIs.
For more about how Trustly’s UI components work, check out the Trustly UI introduction.
This guide walks you through key usage details, including how to configure Establish Data for different scenarios, its base properties, practical examples for common use cases, and troubleshooting tips. Whether you’re working on one-time payments, recurring transactions, or bank account verification, this guide provides you with all the information you need to successfully integrate Trustly.
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 using Establish Data to initiate 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 and if the provided data is valid, will launch a Trustly UI component.
For more details see the Trustly UI sections on Select Bank Widget or Launch the Lightbox.
Establish API (BETA)
An alternative to the Trustly UI, the Establish API can be used to generate a Trustly-hosted web page where a user can complete an authorization. This approach is useful for situations where Trustly cannot be easily integrated into an existing user experience but can also be valuable for early development and testing purposes, simplifying integration and reducing the compliance burden on your side.
Base Properties
The Establish Data object includes several base properties that are essential for successful integration. Below are the key properties you need to configure regardless of use case or industry requirements:
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) |
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. |
merchantReference | String | True | A unique identifier representing the transaction in your system. e.g. Order number or Payment ID number |
returnUrl | String | True | Redirect URL to be called when a user successfully creates a bank authorization. |
cancelUrl | String | True | Redirect URL to be called when a user cancels from the Lightbox or the bank authorization is otherwise unsuccessful. |
notificationUrl | String | False | Notification URL for Trustly to send events (webhooks) associated with this transaction. If provided, overrides the default notification URL configured at the app level during onboarding. |
requestSignature | String | True | Request Signature used to secure the request. See Securing Requests for more information. |
Payment Properties
Payment properties define the key details of the transaction being processed. These fields are essential for specifying the transaction amount, providing context for the end user, and ensuring compliance with payment regulations. Most merchants using Trustly for payments are also required to include customer details, such as a name and address.
Note: Most payment properties will be required if the
paymentType
is set toDeferred
,Instant
orRecurring
.
Parameter | Type | Description |
---|---|---|
amount | Float | For Instant payments, this is the transaction amount.For Deferred payments, this is an optional limit for future capture transactions; the maximum amount of transactions that can be processed. (10 character max) |
currency | String | 3-letter ISO Currency Code. Currently, only USD and CAD are supported. |
description | String | A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field. |
displayAmount | String | The amount to be displayed to the user 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. |
customer | Object | Customer of this payment. If the customer is already created you can send only the customerId attribute inside the customer object. See Customer Object. |
recurrence | Object | Required if paymentType is Recurring . Configuration options for recurring payments. See Recurrence Object. |
metadata | Object | Used to customize components of the Trustly Lightbox. See MetaData Object. |
Example Establish Data Object for a Deferred Payments Authorization.
{
"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"
}
Additional Properties
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 | Description |
---|---|---|
accessId | String | 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 | The gateway redirects the customer browser to this URL if the customer cancels payment (must be a valid URL or function). |
currency | String | 3-letter ISO Currency Code. Currently, only USD and CAD are supported. |
customer | Object | 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 | Your Trustly Merchant Id. It will be provided to you. |
merchantReference | String | 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 | 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 | 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. |
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 . |
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 | Description |
---|---|---|
lang | String | 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. |
flowType | String | Configures the Lightbox to utilize a specific pre-configured user flow. Contact your Trustly point of contact for the flowType options available for your application. |
finishButtonLabelType | String | 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 | 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 | 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 | 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 |
Updated 1 day ago