Webhooks and events

Trustly uses two complementary event systems: server-side webhooks (Event Notifications) to communicate transaction status changes to your backend, and client-side Event Listeners to track user interactions within the Trustly Lightbox.

Event Notifications (Webhooks)

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.

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:

• Default configuration: Contact your Trustly Integration team or Support representative to configure a default notificationUrl in the Trustly administrative interface.
• Per-Transaction: Override the default by passing a specific notificationUrl in the establishData object when you initiate a transaction. See Establish Data for more information.

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

Example Header

Authorization: Basic TThSYUhnRWpCRTU0enVGWU1SUXE6RVlOM0dYYXNyVlUxdlExdXlZejIyTk5RZHk0PQ==

Event headers

An Event notification contains the following headers:

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

Authorize event example

1
{
2
    "merchantId": "000123",
3
    "merchantReference": "unqiueTransactionIdentifier",
4
    "paymentType": "6",
5
    "transactionType": "1",
6
    "eventId": "1028606616",
7
    "eventType": "Authorize",
8
    "objectId": "1024919204",
9
    "objectType": "Transaction",
10
    "message": "",
11
    "timeZone": "Etc/UTC",
12
    "createdAt": "1701986450064",
13
    "accountVerified": "true",
14
    "fiCode": "200005501",
15
    "paymentProviderType": "PWMB",
16
    "status": "2",
17
    "statusMessage": "Authorized",
18
    "splitToken": "CK71sLLEMRAAqahQ2BV4gDo0Duwq+aCs/LRfSDEZGOICTv9VrJXQBxAm6Mf/gGRpTLoUR7tlISHgu5P9fFG6auNEi78QTqaRRod7tfU6ywuS1cffoReSzmAv93m2RZjc="
19
}

Verify the signature

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

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

Available Funds Guidance

If your merchant account is enabled for Available Funds Guidance (AFG), you can use webhook payloads to intelligently recover transactions that fail due to insufficient funds.

When a payment fails, the notification payload may contain a suggestedRetryAmount. This value represents a safe upper limit for a new transaction attempt based on the customer’s available balance at the time of the failure.

Prerequisites: Contact your Trustly Customer Success Manager or Implementation Team to enable Available Funds Guidance for your merchant account.

To implement this recovery logic:

1. Listen for Deny or Failed events where paymentProviderTransaction.status equals SW021 (Insufficient Funds) or SW054 (Security Controls), AND suggestedRetryAmount is greater than 0.
2. Check the payload for the suggestedRetryAmount field.
3. Prompt the customer to retry the payment using the suggested value.

Event Listeners (client-side)

The Trustly SDK provides an addPanelListener function which is used to track user events within the Trustly Lightbox experience. This function is also essential for intercepting the standard browser redirects (returnUrl and cancelUrl) in order to process those final events with JavaScript callbacks directly within your Single Page Application (SPA).

Supported notifications and event types

You can use the addPanelListener function to provide a custom handler to deal with Lightbox events.

Listener example

1
Trustly.addPanelListener((command, obj) => {
2
  switch(command) {
3
    case "open":
4
      console.log("Lightbox will open");
5
      break;
6
7
    case "event":
8
      switch(obj.type) {
9
        case "load":
10
          console.log(
11
            "Lightbox page " + obj.page +
12
            " finished loading for transaction " +
13
            obj.transactionId
14
          );
15
          break;
16
17
        case "bank_selected":
18
          console.log(
19
            "Payment provider having id " + obj.data +
20
            " was selected on the page " + obj.page +
21
            " for transaction " + obj.transactionId
22
          );
23
          break;
24
25
        case "back":
26
          console.log(
27
            "Back button was clicked on the lightbox page " +
28
            obj.page + " for transaction " + obj.transactionId
29
          );
30
          break;
31
32
        case "close":
33
          console.log(
34
            "Lightbox close process was initiated " +
35
            "on the lightbox page " + obj.page +
36
            " with reason " + obj.data +
37
            " for transaction " + obj.transactionId
38
          );
39
          break;
40
41
        case "new_location":
42
          console.log("Browser will be redirected to " + obj.data);
43
          break;
44
      }
45
      break;
46
47
    case "close":
48
      console.log("Lightbox was closed");
49
      break;
50
  }
51
});

Command and event reference

The listener receives two parameters: the high-level command (open, close, event) and the detailed object data.