Introduction

Notifications

API methods with the input parameter NotificationURL will send a UTF-8 encoded notification message using HTTPS POST to the specified NotificationURL to inform the merchant about updates to the order (for example a "credit" notification will be sent for a Deposit to confirm that the payment is completed).

The listening service at the merchant’s server must be accepting HTTPS requests and capable of handling a JSON RPC call. Mixing POST and GET data is not supported so the NotificationURL must not contain a "?" (question mark).

The structure of the notification message depends on the API method. A typical credit notification could look like:

{
    "method": "credit",
    "params": {
        "signature": "R9+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "amount": "902.50",
            "currency": "EUR",
            "messageid": "98348932",
            "orderid": "87654567",
            "enduserid": "32123",
            "notificationid": "9876543456",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {}
        }
    },
    "version": "1.1"
}

📘

All notifications have a unique notificationid.

If the notification was received successfully, the listening service must reply synchronously with a JSON RPC result according to:

{
    "result": {
        "signature": "Jd0hjufbsH0u ... S12Vbz0sw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "credit",
        "data": {
            "status": "..."
        }
    },
    "version":"1.1"
}

🚧

You must respond with the same UUID that you received in the notification.

If the notification could not be delivered due to communication problems or if the listening service did not reply with a valid response, Trustly's system will attempt to send the notification again (with the same notificationid) until it has been successfully delivered.

If the merchant would receive a notification with a notificationid that has already been processed, the notification shall not be processed again but the returned result.data.status must be the same as was returned the first time. This could for example happen if there is a network communication problem with the notification response.

Trustly's system will increase the time in between each retry according to the table below

Retry attempt1234567 to 87
Delay5 sec15 sec45 sec15 min45 min90 min3 hours

If the merchant's listening service has been down for a longer period and then been brought back online again, the merchant can request to send all undelivered notifications immediately, thus ignoring the delay until the next attempt. Such a request has to be ordered manually to Trustly's customer support.

Notification test page

Here you will find our notification test page. This page can be helpful during the integration process, and here you can view the notifications that Trustly has sent in the test environment for a particular order by entering your processing account username (username used in the API calls) and an OrderID. If a notification has not been delivered successfully, you will see the error message for the failed notification here as well.

You will also find a cURL command here for every notification so that you can send the notification yourself. You will also be able to submit notification responses on this page, but to do this you will have to send an additional attribute ("HoldNotifications" : "1") in the Deposit/Withdraw call for which you want to submit the notification responses. This will be helpful if your development server is not reachable from the internet.

Note: the notification test page will only be available for orders created in the test environment.