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:

Parameter	Type	Description
Authorization	String	A 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:

Parameter	Type	Description
merchantId	String	A unique ID that identifies the merchant.
merchantReference	String	A unique identifier from the merchant’s systems such as order 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 notification is associated with (Authorization, Capture, etc).
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. See Object Types.
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
accessId	String	`accessId` that was used when generating the Transaction.
paymentProviderTransaction.status	String
paymentProviderTransaction.statusMessage	String	Payment provider transaction status message.
status	String
statusMessage	String	Status message.
errorCode	String	Error code related to the current status.
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.
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

Type	ID	Description
Update	1	This event occurs when only the payment provider transaction status changes and the Trustly transaction status does not change.
Establish	2	This is the initial event that creates a transaction.
Authorize	3	This event occurs when the transaction is AUTHORIZED.
Process	4	This event occurs when the ACH payment instructions are processed by the bank.
Complete	5	This event occurs when the transaction is considered complete by Trustly. You will be funded for the transaction once this notification is received.
Cancel	6	This event occurs when the transaction is canceled.
Fail	7	This event occurs if some error does not allow the transaction to continue.
Expire	8	This event occurs if the transaction expires before it was completed.
Deny	9	This event occurs when the payment provider denies the payment.
Refund	10	This event occurs when a payment transaction is refunded.
Dispute	11	This event occurs when a payment transaction is disputed.
Reconcile	12	This event happens if the dispute is settled and the transaction is not reversed.
Reverse	13	This event occurs if the transaction is reversed (charged back) after being disputed.
Hold	14	This 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
Approve	15	This event occurs when a transaction that was put on hold due to risk reasons is approved to proceed.
VerifyCustomer	16	This event occurs when the Verify Customer API is called.
VerifyAccount	17	This event occurs when the Verify Financial Institution Account API is called.
SendChallenge	18	This event occurs when a challenged deposit is sent to be processed.
Feedback	19	This 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.
FIUser	20	This event occurs when the Get Financial Institution User is called.
FIAccountBalance	21	This event occurs when the Get Financial Institution Account Balance API is called.
Reclaim	22	This event occurs when a deposit transaction is reclaimed.
ChallengeCompleted	23	This event occurs when the MCD Deposit transactions are completed.
Represent	25	This event occurs when the transaction is represented by the customer or automatically by PayWithMyBank.
SessionStepStart	26
SessionStepComplete	27
SessionStepJSError	28
Refresh	29	This event occurs when the merchants call the API to retrieve the updated account balance
Tokenize	31	This event occurs when the tokenized API is called.
Income	32
FIAccountActivity	33	This event occurs when the merchants call the API to retrieve the account activity.
ReverseEndUserTransaction	37	This event occurs when receiving a completed notification of a transaction that already failed, indicating it was reversed automatically.
FISelectedAccounts	38	This event occurs when the merchants call the API to retrieve multiple selected accounts.