Handle Event Notifications

Trustly uses asynchronous event notifications (webhooks) to communicate transaction status. Because transfers on the Automated Clearing House (ACH) network are not instant, you cannot rely on the immediate API response to determine the final state. You must implement a notification handler to receive and process these updates.

Prerequisites

Before you can handle event notifications, ensure you have completed the following:

Publicly Accessible Endpoint: You must have a publicly accessible HTTPS endpoint on your server to receive POST requests from Trustly.
Security Configuration: You should be prepared to validate the cryptographic signature included in the request headers to ensure the notification is authentic. See Validate the notification signature.

Configure your listener

To receive notifications, you must configure a webhook listener URL. You can configure this URL in two ways:

Merchant Portal: Configure a default notificationUrl in the Settings panel of the Trustly Merchant Portal.
Per-Transaction: Override the default by passing a specific notificationUrl in the establishData object when you initiate a transaction.

Trustly sends a POST request to your endpoint with the event details. Your system must acknowledge receipt by returning a 200 OK status.

Event types

The following table lists the primary event types you will encounter.

Event Type	Description
`Authorize`	The user successfully authorized the transaction with their bank.
`Debited` / `Credit`	Funds have been successfully moved (Captured or Deposited).
`Failed`	The transaction failed (e.g., NSF, Risk, or User Cancel).
`Refresh`	The account balance or data has been refreshed.
`DataReady`	All bank-qualified data (balance, account details) is retrieved and ready for access.

Event payload

Trustly sends event data as a URL-encoded string (application/x-www-form-urlencoded). You must parse this payload to update your internal order status.

Example Payload (Parsed)

{
  "merchantReference": "order-123",
  "transactionId": "1002636615",
  "eventId": "1002636616",
  "eventType": "Authorize",
  "status": "2",
  "statusMessage": "Authorized",
  "paymentType": "2",
  "timestamp": "1632268808515"
}

Verify the signature

To ensure the notification originated from Trustly and has not been tampered with, you must validate the cryptographic signature included in the request headers.

See Validate the notification signature for implementation details and code samples.