Learn about Trustly event notifications (webhooks) and how to accept and process them

What Are Event Notifications?

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.

Receiving Event Notifications

Trustly will send a POST request to the notification endpoint that you provide during initial configuration. Alternatively, provide a notificationUrl property at the time of establishing a new transaction. See Establish Data for more information.

๐Ÿ“˜

Info

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 Securing Requests to validate the request signature provided .

An Event notification contains the following headers:

KeyTypeDescription
AuthorizationStringA Base64 encoded string that can be used to validate the request.

โณ

Sandbox Event Timing

Note that in Trustly's 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 with the following parameters:

ParameterTypeDescription
merchantIdStringA unique ID that identifies the merchant.
merchantReferenceStringA unique identifier from the merchantโ€™s systems such as order ID.
paymentTypeStringIdentifies the type of Payment this notification is associated with. This is provided in the establishData when the Authorization is created.
transactionTypeStringType of Transaction that this notification is associated with (Authorization, Capture, etc).
eventIdStringA unique Trustly event identifier.
eventTypeStringType of Event included in this notification.
objectIdStringA unique ID that identifies this transaction. This will be the transactionId that is returned from the Trustly API or SDK.
objectTypeStringThe type of object this Event is related to. See Object Types.
messageStringOptional event message.
parentObjectIdStringThe unique ID of the parent object if existent.
timeZoneStringTime zone used for createdAt. This will always be Etc/UTC.
createdAtUnix TimestampThe notification creation date and time
accessIdStringaccessId that was used when generating the Transaction.
statusString
statusMessageStringStatus message.
errorCodeStringError code related to the current status.
splitTokenStringOnly 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.
paymentProviderTransaction.statusString
paymentProviderTransaction.statusMessageStringPayment provider transaction status message.
paymentProviderTransaction.reasonCodeEnumThe reasonCode should reflect more detailed information about why the transaction was not accepted successfully.
paymentProviderTransaction.reasonCodeMessageStringA more descriptive description of the event that generated the reason code.

Event Types

Establish

This is the initial event that occurs when a transaction has been created. Typically, this happens when a user has activated the Select Bank Widget or Trustly Lightbox from an application.

{
    "merchantId": "000123",
    "merchantReference": "webhook tests",
    "paymentType": "6",
    "transactionType": "1",
    "eventId": "1028606598",
    "eventType": "Establish",
    "objectId": "1024919204",
    "objectType": "Transaction",
    "message": "establishTransaction",
    "timeZone": "Etc/UTC",
    "createdAt": "1701986347245",
    "status": "0",
    "statusMessage": "New"
}

Authorize

The Authorize event occurs when a new or pending transaction has been successfully authorized by the user. This event is critical as it provides the splitToken value which is required for refreshing bank data and creating payments transactions.

{
    "merchantId": "000123",
    "merchantReference": "webhook tests",
    "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="
}

DataReady

The DataReady event only applies to transactions of the Retrieval type. The delivery of this event indicates that all bank-qualified data has been retrieved and will be available to subsequent requests.

๐Ÿšง

Note

Calling the List Accounts API for a transaction prior to receiving the DataReady event can result in partial data being returned.

{
    "merchantId": "000123",
    "merchantReference": "webhook tests",
    "paymentType": "6",
    "transactionType": "1",
    "eventId": "1028606617",
    "eventType": "DataReady",
    "objectId": "1024919204",
    "objectType": "Transaction",
    "message": "",
    "timeZone": "Etc/UTC",
    "createdAt": "1701986450991"
}

Update

Update events occur when the state of the payment provider changes, for example the user selects a bank from the Trustly Lightbox.

{
    "merchantId": "000123",
    "merchantReference": "webhook tests",
    "paymentType": "6",
    "transactionType": "1",
    "eventId": "1028606610",
    "eventType": "Update",
    "objectId": "1024919204",
    "objectType": "Transaction",
    "message": "setPaymentProvider",
    "timeZone": "Etc/UTC",
    "createdAt": "1701986440726",
    "fiCode": "200005501",
    "fiName": "Demo Bank",
    "status": "1",
    "statusMessage": "Pending"
}

Fail

Fail events occur when a transaction reaches a Failed status.

If the associated transaction is a payment transaction, additional fields beginning with paymentProviderTransaction will be included. More information regarding failed payments can be found in the Payment Decline Codes section of the Type Definition guide.

{
    "merchantId": "00123",
    "merchantReference": "testing_expired_split_token",
    "paymentType": "2",
    "transactionType": "3",
    "eventId": "1030286931",
    "eventType": "Fail",
    "objectId": "1025181233",
    "objectType": "Transaction",
    "message": "Fraud analysis",
    "timeZone": "Etc/UTC",
    "createdAt": "1711658462345",
    "errorCode": "390",
    "paymentProviderTransaction.reasonCode": "4",
    "paymentProviderTransaction.status": "SW054",
    "paymentProviderTransaction.statusMessage": "Fraud analysis",
    "status": "5",
    "statusMessage": "Failed",
    "thirdPartyDeclineCode": "6257206"
}

๐Ÿ‘

Suggested Retry Amounts

If your application is configured for Suggested Retry, a Fail event may contain a suggestedRetryAmount property if the Fail was caused by a risk of insufficient funds. In this case, your application can prompt the user to attempt a new payment using the value of the suggestedRetryAmount as an upper bound.

Other Event Types

TypeDescription
ProcessThis event occurs when the ACH payment instructions are processed by the bank.
CompleteThis event occurs when the transaction is considered complete by Trustly. You will be funded for the transaction once this notification is received.
CancelThis event occurs when the transaction is canceled.
ExpireThis event occurs if the transaction expires before it was completed.
DenyThis event occurs when the payment provider denies the payment.
RefundThis event occurs when a payment transaction is refunded.
DisputeThis event occurs when a payment transaction is disputed.
ReconcileThis event happens if the dispute is settled and the transaction is not reversed.
ReverseThis event occurs if the transaction is reversed (charged back) after being disputed.
HoldThis event occurs when a transaction is put on hold after consumer authorization. This would occur if the ACH gateway were unavailable and will also be used for future risk management
ApproveThis event occurs when a transaction that was put on hold due to risk reasons is approved to proceed.
VerifyCustomerThis event occurs when the Verify Customer API is called.
VerifyAccountThis event occurs when the Verify Financial Institution Account API is called.
SendChallengeThis event occurs when a challenged deposit is sent to be processed.
FeedbackThis event occurs when service feedback is called by the merchant to report back on what is happening with a transaction of payment type Retrieval, which is authorized by us but is processed by a third party.
FIUserThis event occurs when the Get Financial Institution User is called.
FIAccountBalanceThis event occurs when the Get Financial Institution Account Balance API is called.
ReclaimThis event occurs when a deposit transaction is reclaimed.
ChallengeCompletedThis event occurs when the Micro-Challenge Deposit transactions are completed.
RepresentThis event occurs when the transaction is represented by the customer or automatically by PayWithMyBank.
SessionStepStart
SessionStepComplete
SessionStepJSError
RefreshThis event occurs when the merchants call the API to retrieve the updated account balance
TokenizeThis event occurs when the tokenized API is called.
Income
FIAccountActivityThis event occurs when the merchants call the API to retrieve the account activity.
ReverseEndUserTransactionThis event occurs when receiving a completed notification of a transaction that already failed, indicating it was reversed automatically.
FISelectedAccountsThis event occurs when the merchants call the API to retrieve multiple selected accounts.