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.

Event Types

UpdateThis event occurs when only the payment provider transaction status changes and the Trustly transaction status does not change.
EstablishThis is the initial event that creates a transaction.
AuthorizeThis event occurs when the transaction is AUTHORIZED.
ProcessThis event occurs when the ACH payment instructions are processed by the bank.
CompleteThis event occurs when the transaction is considered complete by Trustly. You will be funded for the transaction once this notification is received.
CancelThis event occurs when the transaction is canceled.
FailThis event occurs if some error does not allow the transaction to continue.
ExpireThis event occurs if the transaction expires before it was completed.
DenyThis event occurs when the payment provider denies the payment.
RefundThis event occurs when a payment transaction is refunded.
DisputeThis event occurs when a payment transaction is disputed.
ReconcileThis event happens if the dispute is settled and the transaction is not reversed.
ReverseThis event occurs if the transaction is reversed (charged back) after being disputed.
HoldThis event occurs when a transaction is put on hold after consumer authorization. This would occur if the ACH gateway were unavailable and will also be used for future risk management
FeedbackThis event occurs when service feedback is called by the merchant to report back on what is happening with a transaction of payment type Retrieval, which is authorized by us but is processed by a third party

Did this page help you?