Event Notifications (Webhooks)

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

Receiving Event Notifications

Notifications are Event objects pushed to the merchant server. Trustly will send a POST request to the notification endpoint that you provide. A notification indicates changes to the object referenced in the event, such as changes to the transaction status (authorized, canceled, denied). See Get Transaction 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.

๐Ÿ“˜

Info

Ensure you validate the Notification was sent by Trustly and has not been tampered with by Securing Requests.

Example Header

Authorization: Basic TThSYUhnRWpCRTU0enVGWU1SUXE6RVlOM0dYYXNyVlUxdlExdXlZejIyTk5RZHk0PQ==

An Event notification contains the following headers:

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

Example Request Payload

merchantId=1002463580&merchantReference=cb180040-7210-4ab9-97b7-415824754802&paymentType=2&transactionType=3&eventId=1002593570&eventType=Authorize&objectId=1002593555&objectType=Transaction&message=&timeZone=Etc%2FUTC&createdAt=1556234040954&accessId=M8RaHgEjBE54zuFYMRQq&paymentProviderTransaction.status=AC100&paymentProviderTransaction.statusMessage=AC100&status=2&statusMessage=Authorized

An Event notification body is an application/x-www-form-urlencoded string 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.
paymentProviderTransaction.statusString
paymentProviderTransaction.statusMessageStringPayment provider transaction status message.
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.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

TypeIDDescription
Update1This event occurs when only the payment provider transaction status changes and the Trustly transaction status does not change.
Establish2This is the initial event that creates a transaction.
Authorize3This event occurs when the transaction is AUTHORIZED.
Process4This event occurs when the ACH payment instructions are processed by the bank.
Complete5This event occurs when the transaction is considered complete by Trustly. You will be funded for the transaction once this notification is received.
Cancel6This event occurs when the transaction is canceled.
Fail7This event occurs if some error does not allow the transaction to continue.
Expire8This event occurs if the transaction expires before it was completed.
Deny9This event occurs when the payment provider denies the payment.
Refund10This event occurs when a payment transaction is refunded.
Dispute11This event occurs when a payment transaction is disputed.
Reconcile12This event happens if the dispute is settled and the transaction is not reversed.
Reverse13This event occurs if the transaction is reversed (charged back) after being disputed.
Hold14This 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
Approve15This event occurs when a transaction that was put on hold due to risk reasons is approved to proceed.
VerifyCustomer16This event occurs when the Verify Customer API is called.
VerifyAccount17This event occurs when the Verify Financial Institution Account API is called.
SendChallenge18This event occurs when a challenged deposit is sent to be processed.
Feedback19This 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.
FIUser20This event occurs when the Get Financial Institution User is called.
FIAccountBalance21This event occurs when the Get Financial Institution Account Balance API is called.
Reclaim22This event occurs when a deposit transaction is reclaimed.
ChallengeCompleted23This event occurs when the MCD Deposit transactions are completed.
Represent25This event occurs when the transaction is represented by the customer or automatically by PayWithMyBank.
SessionStepStart26
SessionStepComplete27
SessionStepJSError28
Refresh29This event occurs when the merchants call the API to retrieve the updated account balance
Tokenize31This event occurs when the tokenized API is called.
Income32
FIAccountActivity33This event occurs when the merchants call the API to retrieve the account activity.
ReverseEndUserTransaction37This event occurs when receiving a completed notification of a transaction that already failed, indicating it was reversed automatically.
FISelectedAccounts38This event occurs when the merchants call the API to retrieve multiple selected accounts.