What Are Event Notifications?

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.

Receiving 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.

📘

Info

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:

⏳

Sandbox Event Timing

Note that in Trustly's 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

Conditional Properties

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

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 occurs when a new or pending transaction has been successfully authorized by the user. This event is critical as it provides the splitToken value which is required for refreshing bank data and creating payments transactions.

{
    "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.

🚧

Note

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

Update events occur when the state of the payment provider changes, for example the user selects a bank from the Trustly Lightbox.

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