Event Notifications (Webhooks)
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 OKin less than 3 seconds. If Trustly does not receive a200 OKresponse 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. |
Updated 2 months ago