Initiate an authorization

post

https://sandbox.trustly.one/api/v1/establish

Create a new transaction and generate the URL for the Trustly Lightbox. This is the starting point for any payment or data retrieval flow.

Note: If your application is configured for Money Transfer, additional properties in the customer and beneficiary objects are required.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

createTransaction

boolean

If true, Trustly will return a transactionId that can be used with other API's. Either createTransaction or notify is required.

notify

boolean

If true, Trustly will notify the User via SMS or Email with a URL that can be used to complete the transaction. Either createTransaction or notify is required.

channel

string

Comma separated list of notification channels. Currently only sms and email are supported. Example: sms,email will send a notification via SMS and email to the User. Required if notify is true.

Body Params

merchantId

string

required

length ≥ 1

Your Trustly-provided Merchant ID.

accessId

string

required

length ≥ 1

Your Trustly-provided client application access ID.

amount

string

length ≥ 1

The amount of the transaction. This represents the maximum amount of the transactions that can be processed with the Authorization. If the amount is 0.00, there will be no upper bound on the transaction. (10 characters with support for 2 decimal places)

currency

string

enum

required

length ≥ 1

3-letter ISO Currency Code.

Allowed:

description

string

length ≥ 1

A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.

returnUrl

string

required

length ≥ 1

The URL where the user should be redirected to when the user successfully authorizes the transaction (must be a valid URL or function).

cancelUrl

string

required

length ≥ 1

The URL where the user should be redirected to if the user exits or the transaction is canceled (must be a valid URL or function).

notificationUrl

string

Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured by Trustly during onboarding.

paymentType

string

enum

length ≥ 1

Specifies the type of transaction to create. Possible values are Instant, Deferred, Disbursement, Recurring, Verification, and Retrieval. Default is Retrieval.

Note: If your application is configured for "Money Transfer" and utilizes the "Instant" paymentType several properties under customer, beneficiary and beneficiaryAccount will be required.

See the Money Transfers guide for more details.

Allowed:

requestSignature

string

required

length ≥ 1

Request Signature used to secure the request.

displayAmount

float

Optionally displays the provided transaction amount to the user throughout the Lightbox experience.

merchantReference

string

required

length ≥ 1

A unique identifier that you create to represent the Transaction in the Trustly system.

customer

string

account

object

Account information. Required if paymentType is Verification and a transactionId is not included.

beneficiary

object

The ultimate beneficiary of this payment. Required when using paymentType: Instant for Money Transfer

beneficiaryAccount

object

Financial institution account associated with the ultimate beneficiary of a transaction. Required when using paymentType: Instant for Money Transfer

kycType

string

Specifies the KYC (Know Your Customer) type. This field is optional and can only be used by merchants configured for Trustly ID.

metadata

object

Provide additional use case-specific properties in this object.

Headers

Content-Type

string

Defaults to application/json

application/json

Response

200OK