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:

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 to Deferred, Instant or Recurring.

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.

Recurrence Object

See Capture Transaction for more information on using Trustly for Recurring Payments.

Account Object

Customer Object

Driver License Object

Address Object

Verification Object

Metadata Object

Additional data used for less common scenarios can be provided in the Metadata 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.