Event Notifications (Webhooks)

Receiving Event Notifications

Notifications are Event objects pushed to the merchant server. Trustly will send a POST request to the notification endpoint that you provide. A notification indicates changes to the object referenced in the event, such as changes to the transaction status (authorized, canceled, denied). See Get Transaction for more information.



You must return HTTP status 200 OK in less than 3 seconds. If Trustly does not receive a 200 OK response in 3 seconds, we will retry the notification every 5 minutes for 12 hours.



Ensure you validate the Notification was sent by Trustly and has not been tampered with by Securing Requests.

Example Header

Authorization: Basic TThSYUhnRWpCRTU0enVGWU1SUXE6RVlOM0dYYXNyVlUxdlExdXlZejIyTk5RZHk0PQ==

An Event notification contains the following headers:

AuthorizationStringA Base64 encoded string that can be used to validate the request.

Example Request


An Event notification body is an application/x-www-form-urlencoded string with the following parameters:

merchantIdStringA unique ID that identifies the merchant.
merchantReferenceStringA unique identifier from the merchant’s systems such as order ID.
paymentTypeStringIdentifies the type of Payment this notification is associated with. This is provided in the establishData when the Authorization is created.
transactionTypeStringType of Transaction that this notification is associated with (Authorization, Capture, etc).
eventIdStringA unique Trustly event identifier.
eventTypeStringType of Event included in this notification.
objectIdStringA unique ID that identifies this transaction. This will be the transactionId that is returned from the Trustly API or SDK.
objectTypeStringThe type of object this Event is related to. See Object Types.
messageStringOptional event message.
parentObjectIdStringThe unique ID of the parent object if existent.
timeZoneStringTime zone used for createdAt. This will always be Etc/UTC.
createdAtUnix TimestampThe notification creation date and time
accessIdStringaccessId that was used when generating the Transaction.
paymentProviderTransaction.statusMessageStringPayment provider transaction status message.
statusMessageStringStatus message.
errorCodeStringError code related to the current status.
splitTokenStringOnly sent if enabled for the merchant. Only sent if transactionType = 1 and status = 2. Merchant must store the value and send it back on Capture API calls.
paymentProviderTransaction.reasonCodeEnumThe reasonCode should reflect more detailed information about why the transaction was not accepted successfully.
paymentProviderTransaction.reasonCodeMessageStringA more descriptive description of the event that generated the reason code.

To see a list of Event Types, visit Type Definitions