Handle webhooks

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.

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 event types you may encounter in webhook payloads.

Event Type	Description
`Authorize`	The customer successfully authorized the transaction with their bank.
`Cancel`	A request to cancel the transaction was received.
`Cancelled`	The transaction was successfully canceled by the user, merchant, or system.
`Completed`	The transaction funds have settled.
`CONSENT_REVOKED`	The customer revoked their consent for data access or future payments (currently in development).
`DataReady`	All bank-qualified data (balance, account details) is retrieved and ready for access.
`Deny`	The transaction was denied (for example, due to insufficient funds or high risk).
`Dispute`	A dispute or chargeback was initiated for the transaction.
`Establish`	The transaction was created and is awaiting user interaction.
`Expire`	The transaction session expired before it could be completed.
`Failed`	The transaction failed (for example, due to technical errors or user abandonment).
`Process`	Trustly has submitted the transaction to the banking network for processing.
`Reconcile`	The transaction has been reconciled.
`Refresh`	The account balance or data has been refreshed.
`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).
`Update`	The transaction details or status have been updated.

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 (raw)

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, Trustly recommends validating the cryptographic signature included in the Authorization request header.

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

Available Funds Guidance

While Available Funds Guidance (AFG) is fundamentally a payments feature, its technical implementation relies on webhook data. If your merchant account is enabled for 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

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

Handle the event

To implement this recovery logic in your application:

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

Example event payload (raw)

merchantReference=order-123&transactionId=1002636615&eventType=Deny&status=8&paymentProviderTransaction.status=SW021&message=Not+enough+balance&suggestedRetryAmount=500.00