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

Event types

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

Event payload

Trustly sends event data as a URL-encoded string (application/x-www-form-urlencoded). You must parse these name-value pairs 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 Authorization header of the request.

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

Available Funds Guidance

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

When a transaction 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:

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.

Example event payload (parsed)

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