For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
This endpoint creates a new unauthorized transaction and returns a URL to be provided for a user to authorize the transaction. After the user has authorized the transaction with a bank, the transaction can be used with other Trustly APIs to retrieve account data or process payments.
For more details and descriptions of the fields supported by this endpoint see [Establish Data object](doc:features/establish-data-object).
> **Note for Money Transfer**
> If your application is configured for "Money Transfer" many properties in the `customer`, `beneficiary` and `beneficiaryAccount` objects will be required.
> See [Send money](/integrate/send-money) for more details.
Authentication
AuthorizationBasic
Query parameters
createTransactionbooleanOptional
If true, Trustly will return a transactionId that can be used with other API's. Either createTransaction or notify is required.
notifybooleanOptional
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.
channelstringOptional
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.
Request
merchantIdstringRequired>=1 character
Your Trustly-provided Merchant ID.
accessIdstringRequired>=1 character
Your Trustly-provided client application access ID.
currencyenumRequired
3-letter ISO Currency Code.
Allowed values:
returnUrlstringRequired>=1 character
The URL where the user should be redirected to when the user successfully authorizes the transaction (must be a valid URL or function).
cancelUrlstringRequiredformat: "">=1 character
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).
requestSignaturestringRequired>=1 character
Request Signature used to secure the request.
merchantReferencestringRequired>=1 character
A unique identifier that you create to represent the Transaction in the Trustly system.
amountstringOptional>=1 character
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)
descriptionstringOptional>=1 character
A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.
notificationUrlstringOptional
Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured by Trustly during onboarding.
paymentTypeenumOptional
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 [Send money](/integrate/send-money) for more details.
displayAmountdoubleOptional
Optionally displays the provided transaction amount to the user throughout the Lightbox experience.
customerobjectOptional
The Trustly customer object, containing identification details and contact information.
accountobjectOptional
Account information. Required if paymentType is Verification and a transactionId is not included.
beneficiaryobjectOptional
The ultimate beneficiary of this payment. Required when using paymentType: Instant for Money Transfer
beneficiaryAccountobjectOptional
Financial institution account associated with the ultimate beneficiary of a transaction. Required when using paymentType: Instant for Money Transfer
kycTypestringOptional
Specifies the KYC (Know Your Customer) type. This field is optional and can only be used by merchants configured for Trustly ID.
metadataobjectOptional
Provide additional use case-specific properties in this object.
Response
OK
urlstring>=1 character
merchantIdstring
Your Merchant ID.
paymentTypedouble
The Payment Type of the transaction to create. Currently only Disbursement, Deferred, and Instant are supported.
returnUrlstring
Return URL to use when the transaction is completed.
cancelUrlstring
Cancel URL to use if the user cancels the transaction.
notificationUrlstring
Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured at the merchant level.
datastring
accessIdstring
Your client application access id. It will be provided to you.
requestSignaturestring
Request Signature that can be validated to verify the response authenticity.
transactionIdstring
Transaction ID retrieved from Trustly.
merchantReferencestring
An external reference from the merchant. Ex: Order identifier from merchant e-commerce application.
descriptionstring
Merchant order description
currencyenum
3-letter ISO Currency Code. Currently only USD is supported.
kycTypeenum
Specifies the KYC (Know Your Customer) type as number. The possible value is 1 (OnlineBanking). This field is optional and can only be used by merchants configured for Trustly ID.
amountstring
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)
verificationobject
customerobject
The Trustly customer object, containing identification details and contact information.
accountobject
metadataobject
trustlyABRequestobject
This endpoint creates a new unauthorized transaction and returns a URL to be provided for a user to authorize the transaction. After the user has authorized the transaction with a bank, the transaction can be used with other Trustly APIs to retrieve account data or process payments.
For more details and descriptions of the fields supported by this endpoint see Establish Data object.
Note for Money Transfer
If your application is configured for “Money Transfer” many properties in the customer, beneficiary and beneficiaryAccount objects will be required.
See Send money for more details.
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.
