Notyfikacje

Dla poprawnej konfiguracji wysyłki notyfikacji, należy wprowadzić odpowiedni adres url notyfikacji w panelu administracyjnym imoje lub w zapytaniu w ramach opcjonalnego parametru notificationUrl.

Aby dodać adres należy po zalogowaniu się do panelu imoje przejść do zakładki Sklepy, później należy wybrać sklep w którym wykonywana jest integracja i kliknąć w Szczegóły. Następnie przejść do sekcji Dane do integracji i edytować pole Adres notyfikacji.

W momencie zmiany statusu transakcji serwery imoje wysyłają powiadomienia na wskazany przez akceptanta adres URL. Wymagane jest by serwer akceptanta odpowiedział statusem 200 OK z body {"status":"ok"}, który będzie oznaczał poprawne odebranie i przetworzenie notyfikacji przez serwer akceptanta. Notyfikacje wysyłane są w następującym cyklu:

• 3 razy co 10 sekund, następnie
• 5 razy co 5 minut, następnie
• 5 razy co 60 minut, następnie
• 5 razy co 360 minut, następnie
• 5 razy co 720 minut

W przypadku otrzymania z serwerów imoje dwóch identycznych notyfikacji pierwszą należy obsłużyć zgodnie z punktem metoda weryfikacji podpisu notyfikacji, natomiast drugą (duplikat) należy zignorować.

Notyfikacja może składać się z następujących obiektów:

• transaction - zawiera informacje o transakcji jeśli została utworzona po wybraniu metody płatności przez płatnika
• payment - zawiera informacje o utworzonym linku płatności
• action - zawiera informacje na temat danych użytych do przekierowania na zewnętrzną stronę banku
• paymentProfile - zawiera informacje na temat utworzonego profilu kartowego Oneclick/Recurring

Parametry notyfikacji

Parametry dla obiektu transaction:

Parametry dla obiektu payment:

Parametry dla obiektu action:

Parametry dla obiektu paymentProfile:

Przykładowa zawartość BODY notyfikacji

{
    "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": ""
    }
}

Zawartość nagłówków notyfikacji

Dodatkowo w nagłówkach HTTP umieszczane są następujące parametry:

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

gdzie:

• merchantid - identyfikator klienta
• serviceid - identyfikator sklepu
• signature - podpis notyfikacji
• alg - algorytm funkcji skrótu, dopuszczalne wartości: sha224, sha256, sha384, sha512

Przykład nagłówka X-Imoje-Signature

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

Metoda weryfikacji podpisu notyfikacji

Weryfikacja podpisu notyfikacji jest krytycznym elementem uwierzytelnienia informacji przesyłanych w pakiecie notyfikacji.

Nagłówek zawierający podpis notyfikacji ma postać:

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

Aby uwierzytelnić pochodzenie oraz zweryfikować integralność wiadomości powiadomienia należy wykonać następujące czynności:

1. Z nagłówków pakietu przychodzącego na adres notyfikacji należy pobrać zawartość X-IMoje-Signature,
2. Następnie należy pobrać wartość parametru signature oraz alg,

3. W zależności od algorytmu funkcji skrótu określonego w parametrze alg należy obliczyć odpowiednią funkcją skrót:

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

4. Obliczoną wartość own_signature należy porównać z wartością incoming_signature, która została pobrana z nagłówka,

5. Jeżeli wartości own_signature i incoming_signature są identyczne oznacza to, że wiadomość notyfikacji jest poprawna i pochodzi z zaufanego źródła.

Przykład weryfikacji podpisu notyfikacji

1. W nagłówku otrzymujemy sygnaturę imoje:

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

2. W treści pakietu notyfikacji otrzymujemy 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. Obliczamy sygnaturę:

   service_key: PIcMy86ssE5wuNHAuQn5zPKf6hCAwX3Oxvjw

   own_signature = sha256(body + service_key)

   own_signature: b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23

2. Porównujemy sygnaturę obliczoną z otrzymaną w nagłówku notyfikacji:

const crypto = require('crypto')
let body = "{...}";
let headerSignature = "b73321c9e8bcc414b8c08198db4084dafb1b4dc252f512ffe71b1fbce857fd23";
let privateKey = "PIcMy86ssE5wuNHAuQn5zPKf6hCAwX3Oxvjw";
let mySignature = crypto.createHash("sha256").update(body + privateKey).digest("hex");
if (mySignature === headerSignature) {
    // Notyfikacja zweryfikowana poprawnie. Przetwarzaj dalej.
} else {
    // Notyfikacja zweryfikowana negatywnie. Ignoruj notyfikację.
}

Notyfikacje do raportów

Dla raportów planowanych możliwe jest odbieranie notyfikacji o możliwości pobrania gotowego raportu.

W tym celu po zalogowaniu się do panelu administracyjnego imoje należy przejść do zakładki Raporty, a następnie w sekcji Raporty planowane wybrać opcję Dodaj raport. Oprócz uzupełnienia pożądanych parametrów w formularzu należy wprowadzić także Adres notyfikacji, który będzie odbierał notyfikacje na temat dostępności raportu.

Notyfikacje do raportów wysyłane są jako obiekt JSON metodą POST i mają następującą postać:

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

Notyfikacja może składać się z następujących parametrów:

Notyfikacje do zwrotów

Domyślnie nie wysyłamy notyfikacji do zwrotów.

Jeśli jednak chcesz je otrzymywać, to skontaktuj się z nami pod adresem kontakt.tech@imoje.pl. W treści swojego mejla podaj identyfikator sklepu, dla którego chcesz włączyć notyfikacje do zwrotów.