Skip to navigation
APITransactions

Establish a new transaction for authorization

View as Markdown

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.

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

This endpoint expects an object.
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 for more details.

displayAmountstringOptional>=1 character

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

Note: This value must be sent as a JSON string (for example, "10.50"), not as a numeric value.

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
merchantIdstringOptional
Your Merchant ID.
paymentTypedoubleOptional
The Payment Type of the transaction to create. Currently only Disbursement, Deferred, and Instant are supported.
returnUrlstringOptional
Return URL to use when the transaction is completed.
cancelUrlstringOptional
Cancel URL to use if the user cancels the transaction.
notificationUrlstringOptional
Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured at the merchant level.
datastringOptional
accessIdstringOptional
Your client application access id. It will be provided to you.
requestSignaturestringOptional
Request Signature that can be validated to verify the response authenticity.
transactionIdstringOptional
Transaction ID retrieved from Trustly.
merchantReferencestringOptional

An external reference from the merchant. Ex: Order identifier from merchant e-commerce application.

descriptionstringOptional
Merchant order description
currencyenumOptional

3-letter ISO Currency Code. Currently only USD is supported.

Allowed values:
kycTypeenumOptional

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.

Allowed values:
amountstringOptional

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)

verificationobjectOptional
customerobjectOptional
The Trustly customer object, containing identification details and contact information.
accountobjectOptional
metadataobjectOptional
trustlyABRequestobjectOptional