Notifications

For the correct configuration of notification sending, enter the appropriate notification URL in the imoje administration panel.

To add an address, log in to the imoje panel, go to the Shops tab, select the shop where the integration is performed, and click on Details. Then go to the Integration data section and edit the Notification address field.

When the transaction status changes, imoje servers send notifications to the URL specified in the administration panel. The merchant's server (e.g. shop) is required to respond with status 200 OK with body {'status':'ok'}, which will indicate that the notification has been correctly received and processed by the merchant's server. Notifications are sent in the following cycle:

• 3 times every 10 seconds, then
• 5 times every 5 minutes, then
• 5 times every 60 minutes, then
• 5 times every 360 minutes, then
• 5 times every 720 minutes.

If two identical notifications are received from imoje servers, the first one should be handled in accordance with the section notification signature verification method, while the second one (duplicate) should be ignored.

The notification may consist of the following objects:

• transaction - contains information about the transaction if it was created after the payer selected the payment method
• payment - contains information about the payment link created
• action - contains information about the data used to redirect to the external bank website
• paymentProfile - contains information about the created Oneclick/Recurring card profile

Notification parameters

Parameters for the transaction object:

Parameters for the payment object:

Parameters for the action object:

Parameters for the paymentProfile object:

Example content of the notification BODY

{
    "transaction": {
        "id": "07938437-cae3-4d46-877d-e1b9d6e6c58f",
        "type": "sale",
        "status": "pending",
        "source": "api",
        "created": 1666339083,
        "modified": 1666339083,
        "notificationUrl": "https://yourshopdomain.com/notification",
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "amount": 1000,
        "currency": "PLN",
        "title": "yourTitle",
        "orderId": "yourOrderId",
        "paymentMethod": "blik",
        "paymentMethodCode": "blik"
    },
    "payment": {
        "id": "07980a69-a884-46f7-ad16-216c88a13b98",
        "title": "yourTitle",
        "amount": 1000,
        "status": "pending",
        "created": 1666339083,
        "orderId": "yourOrderId",
        "currency": "PLN",
        "modified": 1666339083,
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "notificationUrl": "https://yourshopdomain.com/notification"
    },
    "action": {
        "type": "redirect",
        "url": "https://paywall.imoje.pl/07980a69-a884-46f7-ad16-216c88a13b98",
        "method": "GET",
        "contentType": "",
        "contentBodyRaw": ""
    }
}

Notification header content

Additionally, the following parameters are included in HTTP headers:

Accept: "text/plain",
User-Agent: "imoje",
Content-Type: "application/json; charset=UTF-8",
X-Imoje-Signature: "merchantid={merchantid};serviceid={serviceid};signature={signature};alg={alg}"

where:

• merchantid - customer ID
• serviceid - shop ID
• signature - notification signature
• alg - hash function algorithm, acceptable values: sha224, sha256, sha384, sha512

Example of an X-Imoje-Signature header

X-Imoje-Signature: "merchantid=6yt3gjtm9p7b8h9xsdqz;serviceid=63f574ed-d4ad-407e-9981-39ed7584a7b7;signature=20cdc8646eb268ea754842bdf0db1df21a2cf0b1c6e3e16e74ef7f7cca8f5450;alg=sha256"

Notification signature verification method

Verification of the notification signature is a critical element of authenticating the information sent in the notification package.

The header containing the notification signature has the following form:

X-Imoje-Signature: merchantid=[...];serviceid=[...];signature=[...];alg=[...]

To authenticate the origin and verify the integrity of the notification message, perform the following steps:

1. From the headers of the incoming package to the notification address, retrieve the content of X-IMoje-Signature.
2. Then retrieve the values of the signature and alg parameters.

3. Depending on the hash function algorithm specified in the alg parameter, calculate the appropriate hash function:

   string incoming_signature = x_imoje_signature[signature]
   string body = notification_body
   string own_signature = hash(body + service_key, alg)
   

4. The calculated value of own_signature should be compared with the value of incoming_signature, which was retrieved from the header.

5. If the values of own_signature and incoming_signature are identical, it means that the notification message is valid and comes from a trusted source.

Example of notification signature verification

1. The header contains the imoje signature:

   X-Imoje-Signature: merchantid=mdy7zxvxudgarxbsou9n;serviceid=a33f331b-23fc-42b0-9fd1-67f310028b46;signature=b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23;alg=sha256
   

2. In the notification package, you receive JSON:

{
    "transaction": {
        "id": "07938437-cae3-4d46-877d-e1b9d6e6c58f",
        "type": "sale",
        "status": "pending",
        "source": "api",
        "created": 1666339083,
        "modified": 1666339083,
        "notificationUrl": "https://yourshopdomain.com/notification",
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "amount": 100,
        "currency": "PLN",
        "title": "",
        "orderId": "Zamowienie test",
        "paymentMethod": "pbl",
        "paymentMethodCode": "ipko"
    },
    "payment": {
        "id": "07980a69-a884-46f7-ad16-216c88a13b98",
        "title": "",
        "amount": 100,
        "status": "pending",
        "created": 1666339083,
        "orderId": "Zamowienie test",
        "currency": "PLN",
        "modified": 1666339083,
        "serviceId": "a33f331b-23fc-42b0-9fd1-67f310028b46",
        "notificationUrl": "https://yourshopdomain.com/notification"
    },
    "action": {
        "type": "redirect",
        "url": "https://paywall.imoje.pl/07980a69-a884-46f7-ad16-216c88a13b98",
        "method": "GET",
        "contentType": "",
        "contentBodyRaw": ""
    }
}

1. Calculate the signature:

   service_key:PIcMy86ssE5wuNHAuQn5zPKf6hCAwX3Oxvjw

   own_signature = sha256(body + service_key)

   own_signature:b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23

2. Compare the calculated signature with the one received in the notification header:

const crypto = require('crypto')
let body = "{...}";
let headerSignature = "b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23";
let serviceKey = "PIcMy86ssE5wuNHAuQn5zPKf6hCAwX3Oxvjw";
let mySignature = crypto.createHash("sha256").update(body + serviceKey).digest("hex");
if (mySignature === headerSignature) {
    // Notification verified correctly. Continue processing.
} else {
    // Notification verified as negative. Ignore notification.
}

Notifications for reports

For scheduled reports, it is possible to receive notifications about the availability of the finished report.

To do this, after logging in to the imoje administration panel, go to the Reports tab, and then in the Scheduled reports section, select the Add report option. In addition to filling in the desired parameters in the form, you must also enter the Notification address, which will receive notifications about the availability of the report.

Notifications for reports are sent as a JSON object using the POST method and have the following form:

{
    "id": "57526046-db6a-45f9-8288-284337129a8f",
    "status": "generated",
    "fileExt": "owi1",
    "created": 1540382655,
    "modified": 1705398343,
    "url": "https://imoje.ing.pl/351e2776166edaf0e867e3231e518111b17580baa650c90764e671de57465e08c90ef7751600ef7107cdf7628ffced66bd85360776bf0b713881cbc9b9230c83"
}

The notification may consist of the following parameters:

Refund notifications

By default, we do not send return notifications.

However, if you would like to receive them, please contact us at kontakt.tech@imoje.pl. In your email, please include the ID of the shop for which you would like to enable return notifications.