Event Notifications are Event objects pushed to the merchant server. A notification indicates changes to the object referenced in the event, such as changes to the transaction status (authorized, canceled, denied). For most use cases, receiving and processing event notifications is required to successfully integrate a Trustly product.

Receive Event Notifications

Trustly will send a POST request to the notification endpoint that you provide during initial configuration. Alternatively, provide a notificationUrl property at the time of establishing a new transaction. See Establish Data 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.

** Example Header**

Authorization: Basic TThSYUhnRWpCRTU0enVGWU1SUXE6RVlOM0dYYXNyVlUxdlExdXlZejIyTk5RZHk0PQ==

🔒
Security
Ensure you verify the event notification was sent by Trustly and has not been tampered with by following the steps in Securing Requests to validate the request signature provided .

An Event notification contains the following headers:

Key	Type	Description
Authorization	String	A Base64 encoded string that can be used to validate the request.
Content-Type	String	application/x-www-form-urlencoded

⏳
Sandbox Event Timing
In the Trustly Sandbox environment, some asynchronous notifications such as payout processing are run in batches every 300 seconds (5 minutes).

Event Properties

An Event notification body is an application/x-www-form-urlencoded string containing various data points. All events contain at a minimum, the following parameters:

Primary Properties

Parameter	Type	Description
merchantId	String	Unique ID assigned to the merchant associated with the event.
merchantReference	String	A unique identifier from the merchant’s systems such as order ID or payment ID.
paymentType	String	Identifies the type of Payment this notification is associated with. This is provided in the `establishData` when the Authorization is created.
transactionType	String	Type of Transaction that this event is associated with e.g. Authorization, Capture. See Transaction Types for more details.
eventId	String	A unique Trustly event identifier.
eventType	String	Type of Event included in this notification.
objectId	String	A unique ID that identifies this transaction. This will be the `transactionId` that is returned from the Trustly API or SDK.
objectType	String	The type of object this Event is related to. See Object Types.
message	String	Optional event message.
parentObjectId	String	The unique ID of the parent object if existent.
timeZone	String	Time zone used for `createdAt`. This will always be `Etc/UTC`.
createdAt	Unix Timestamp	The notification creation date and time
status	Integer	Transaction status at time of event see all possible transaction status types
statusMessage	String	Human readable Status message.

Conditional Properties

The following properties are included on some events based on the transactionType and eventType:

Parameter	Type	Description
splitToken	String	Only 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.
errorCode	String	Error code related to the current status if the event was generated by an error status event.
suggestedRetryAmount	String	Suggested amount for payment retry if the associated payment transaction failed due to spending limits or risk of insufficient funds. See Spending Limits for more details.
paymentProviderTransaction.status	String
paymentProviderTransaction.statusMessage	String	Payment provider transaction status message.
paymentProviderTransaction.reasonCode	Enum	The reasonCode should reflect more detailed information about why the transaction was not accepted successfully.
paymentProviderTransaction.reasonCodeMessage	String	A more descriptive description of the event that generated the reason code.

Event Types

Establish

This is the initial event that occurs when a transaction has been created. Typically, this happens when a user has activated the Select Bank Widget or Trustly Lightbox from an application.

Schema and examples for the Establish Event

Authorize

The Authorize event indicates that the user has successfully authorized the transaction with their bank.

{
    "merchantId": "000123",
    "merchantReference": "unqiueTransactionIdentifier",
    "paymentType": "6",
    "transactionType": "1",
    "eventId": "1028606616",
    "eventType": "Authorize",
    "objectId": "1024919204",
    "objectType": "Transaction",
    "message": "",
    "timeZone": "Etc/UTC",
    "createdAt": "1701986450064",
    "accountVerified": "true",
    "fiCode": "200005501",
    "paymentProviderType": "PWMB",
    "status": "2",
    "statusMessage": "Authorized",
    "splitToken": "CK71sLLEMRAAqahQ2BV4gDo0Duwq+aCs/LRfSDEZGOICTv9VrJXQBxAm6Mf/gGRpTLoUR7tlISHgu5P9fFG6auNEi78QTqaRRod7tfU6ywuS1cffoReSzmAv93m2RZjc="
}

DataReady

The DataReady event only applies to transactions of the Retrieval type. The delivery of this event indicates that all bank-qualified data has been retrieved and will be available to subsequent requests.

Calling the List Accounts API for a transaction prior to receiving the DataReady event can result in partial data being returned.

Schema and examples for the DataReady Event

Update

The Update event indicates that the status of a transaction has changed. For example, when a transaction moves from Pending to Authorized.

Schema and examples for the Update Event

Fail

Fail events occur when a transaction reaches a Failed status.

If the associated transaction is a payment transaction, additional fields beginning with paymentProviderTransaction will be included. More information regarding failed payments can be found in the Payment Decline Codes section of the Type Definition guide.

🅱️
BETA feature: Available Funds Guidance
If your application is configured for Available Funds Guidance, a Fail or Deny event may contain a suggestedRetryAmount property if the event was caused by a risk of insufficient funds. In this case, your application can prompt the user to attempt a new payment using the value of the suggestedRetryAmount as an upper bound.

Schema and examples for the Failed Event

Deny

This event occurs when the payment provider denies the payment.

Deny events will include paymentProviderTransaction data. More information regarding failed payments can be found in the Payment Decline Codes section of the Type Definition guide.

{
    "merchantId": "00123",
    "merchantReference": "unqiueTransactionIdentifier",
    "paymentType": "2",
    "transactionType": "3",
    "eventId": "1030845856",
    "eventType": "Deny",
    "objectId": "1025228290",
    "objectType": "Transaction",
    "message": "Not enough balance",
    "timeZone": "Etc/UTC",
    "createdAt": "1714503865362",
    "errorCode": "331",
    "paymentProviderTransaction.reasonCode": "12",
    "paymentProviderTransaction.reasonCodeMessage": "Not enough balance",
    "paymentProviderTransaction.status": "SW021",
    "paymentProviderTransaction.statusMessage": "Not enough balance",
    "status": "8",
    "statusMessage": "Denied"
}

Other Event Types

Type	Description
Process	This event occurs when the ACH payment instructions are processed by the bank.
Complete	This event occurs when the transaction is considered complete by Trustly. You will be funded for the transaction once this notification is received.
Cancel	This event occurs when the transaction is canceled.
Expire	This event occurs if the transaction expires before it was completed.
Refund	This event occurs when a payment transaction is refunded.
Dispute	This event occurs when a payment transaction is disputed.
Reconcile	This event happens if the dispute is settled and the transaction is not reversed.
Reverse	This event occurs if the transaction is reversed (charged back) after being disputed.
Hold	This 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
Approve	This event occurs when a transaction that was put on hold due to risk reasons is approved to proceed.
VerifyCustomer	This event occurs when the Verify Customer API is called.
VerifyAccount	This event occurs when the Verify Financial Institution Account API is called.
SendChallenge	This event occurs when a challenged deposit is sent to be processed.
Feedback	This 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.
FIUser	This event occurs when the Get Financial Institution User is called.
FIAccountBalance	This event occurs when the Get Financial Institution Account Balance API is called.
Reclaim	This event occurs when a deposit transaction is reclaimed.
ChallengeCompleted	This event occurs when the Micro-Challenge Deposit transactions are completed.
Represent	This event occurs when the transaction is represented by the customer or automatically by PayWithMyBank.
SessionStepStart
SessionStepComplete
SessionStepJSError
Refresh	This event occurs when the merchants call the API to retrieve the updated account balance
Tokenize	This event occurs when the tokenized API is called.
Income
FIAccountActivity	This event occurs when the merchants call the API to retrieve the account activity.
ReverseEndUserTransaction	This event occurs when receiving a completed notification of a transaction that already failed, indicating it was reversed automatically.
FISelectedAccounts	This event occurs when the merchants call the API to retrieve multiple selected accounts.