> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://amer.developers.trustly.com/llms.txt. > For full documentation content, see https://amer.developers.trustly.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # 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](/integrate/api-fundamentals/secure-requests-and-signature-validation/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](/integrate/core-concepts/the-establish-data-object) 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. 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 [Secure Requests](/integrate/api-fundamentals/secure-requests-and-signature-validation) to validate the request signature provided. ### Event headers 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. | | 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. | | 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 | | 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. | | 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 | Event Type | Description | | :---------------- | :------------------------------------------------------------------------------------------------ | | `Establish` | The transaction was created and is awaiting user interaction. | | `Authorize` | The customer successfully authorized the transaction with their bank. | | `DataReady` | All bank-qualified data (balance, account details) is retrieved and ready for access. | | `Update` | The transaction details or status have been updated. | | `Process` | Trustly has submitted the transaction to the banking network for processing. | | `Complete` | The transaction funds have settled. | | `Cancel` | A request to cancel the transaction was received. | | `Cancelled` | The transaction was successfully canceled by the user, merchant, or system. | | `Expire` | The transaction session expired before it could be completed. | | `Failed` | The transaction failed (for example, due to technical errors or user abandonment). | | `Deny` | The transaction was denied (for example, due to insufficient funds or high risk). | | `Dispute` | A dispute or chargeback was initiated for the transaction. | | `Reconcile` | The transaction has been reconciled. | | `Refund` | A refund was initiated or processed for the transaction. | | `Reverse` | The transaction was completed but later returned (for example, an administrative or ACH return). | | `Refresh` | The account balance or data has been refreshed. | | `CONSENT_REVOKED` | The customer revoked their consent for data access or future payments (currently in development). | ### Authorize event example ```json { "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=" } ``` ### 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](/integrate/api-fundamentals/secure-requests-and-signature-validation/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. The JavaScript window event notification call below only works on native apps when the Trustly SDK is used or if the merchant implements the creation of new windows. ### Listener example ```javascript Trustly.addPanelListener((command, obj) => { switch(command) { case "open": console.log("Lightbox will open"); break; case "event": switch(obj.type) { case "load": console.log( "Lightbox page " + obj.page + " finished loading for transaction " + obj.transactionId ); break; case "bank_selected": console.log( "Payment provider having id " + obj.data + " was selected on the page " + obj.page + " for transaction " + obj.transactionId ); break; case "back": console.log( "Back button was clicked on the lightbox page " + obj.page + " for transaction " + obj.transactionId ); break; case "close": console.log( "Lightbox close process was initiated " + "on the lightbox page " + obj.page + " with reason " + obj.data + " for transaction " + obj.transactionId ); break; case "new_location": console.log("Browser will be redirected to " + obj.data); break; } break; case "close": console.log("Lightbox was closed"); break; } }); ``` ### Command and event reference The listener receives two parameters: the high-level command (`open`, `close`, `event`) and the detailed object data. | Command/Event Type | Command/Type Data | Description | | :---------------------- | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open` (Command) | - | Triggered immediately when the Trustly Lightbox opens. | | `close` (Command) | - | Triggered when the Trustly Lightbox finishes closing. | | `event` (Command) | - | Triggered when a specific user action or internal change occurs within the Lightbox. | | `load` (Event) | `{ page, transactionId }` | Triggered when a specific page finishes loading. `page` contains the name of the loaded page. | | `loading` (Event) | `{ page, transactionId }` | Triggered when page content loading is active. This can be useful for displaying spinners or progress indicators. | | `bank_selected` (Event) | `{ page, transactionId, data, transfer }` | Triggered when a user selects a bank tile. `data` is the `paymentProviderId`. `transfer.paymentProvider` contains the bank details (ID and name). | | `back` (Event) | `{ page, transactionId }` | Triggered when a user clicks the back button or navigates to the previous page in the flow. | | `close` (Event) | `{ page, transactionId, data: reason }` | Triggered when the Lightbox close process is initiated. `reason` will be `"return"` or `"cancel"`. | | `new_location` (Event) | `{ data: newLocation }` | Crucial for SPA integration. Triggered when the flow is complete and the user is about to be redirected to the `returnUrl` or `cancelUrl`. `newLocation` contains the final URL with return parameters. You can process the final result using this data and prevent the browser redirect. |