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.


Notyfikacje są wysyłane z adresów IP z poniższych zakresów CIDR: 5.196.116.32/28, 51.195.95.0/28, 54.37.185.64/28, 54.37.185.80/28, 147.135.151.16/28


Notyfikacje wysyłane są na domyślne porty HTTP (80) i HTTPS (443).

W momencie zmiany statusu transakcji serwery imoje wysyłają powiadomienia na wskazany przez akceptanta adres URL. Wymagane jest by serwer akceptanta (np. sklep) 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.


Jeśli serwer akceptanta zwróci status 200 OK, lub notyfikacja nie zostanie odebrana do czasu zakończenia trwania całego cyklu, serwery imoje zaprzestają powtórzeń wysyłki notyfikacji.

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


Obiekt payment będzie jedynym wysłanym obiektem, gdy link płatności straci swój czas ważności lub zostanie ręcznie anulowany.

Parametry notyfikacji

Parametry dla obiektu transaction:
Parametr Typ Opis
id string(36) Identyfikator transakcji UUID v4
type string Typ transakcji, dopuszczalne wartości: sale, refund
status string Status transakcji, dopuszczalne wartości: new, pending, authorized, settled, cancelled, rejected
source string Źródło transakcji, dopuszczalne wartości: api, web
created integer(10) Data utworzenia transakcji
modified integer(10) Data modyfikacji transakcji
notificationUrl varchar(300) Adres notyfikacji
serviceId string(36) Identyfikator sklepu UUID v4
amount integer(9) Kwota transakcji, maksymalna wartość: 999999999
currency string(3) Waluta transakcji w standardzie ISO 4217
title string(255) Tytuł zamówienia, dopuszczalne znaki: A-Za-z0-9#&_-"',./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne)
orderId string(100) Numer zamówienia, dopuszczalne znaki: A-Za-z0-9#_-./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne)
paymentMethod string Metoda realizacji zamówienia.
paymentMethodCode string Oznaczenie kanału płatności.
statusCode string(24) Kod statusu zwracany do transakcji kartami
statusCodeDescription string(113) Opis kodu statusu zwracany do transakcji kartami


Parametry dla obiektu payment:
Parametr Typ Opis
id string(36) Identyfikator zamówienia UUID v4
title string(255) Tytuł zamówienia, dopuszczalne znaki: A-Za-z0-9#&_-"',./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne)
amount integer(9) Kwota zamówienia, maksymalna wartość: 999999999
status string Status zamówienia, dopuszczalne wartości: new, pending, settled, cancelled, rejected
created integer(10) Data utworzenia zamówienia
orderId string(100) Numer zamówienia, dopuszczalne znaki: A-Za-z0-9#_-./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne)
currency string(3) Waluta zamówienia w standardzie ISO 4217
modified integer(10) Data modyfikacji zamówienia
serviceId string(36) Identyfikator sklepu UUID v4
notificationUrl varchar(300) Adres notyfikacji
ipksef string Identyfikator płatności KSeF


Parametry dla obiektu action:
Parametr Typ Opis
type string Typ przekierowania, dopuszczalne wartości: redirect, transfer
url string(2083) Adres przekierowania
method string Metoda przekierowania, dopuszczalne wartości: POST, GET
contentType varchar(100) Typ formatu danych
contentBodyRaw text Parametry przekierowania
ban string(26) Numer rachunku bankowego, zwracany dla metody płatności Przelew tradycyjny


Parametry dla obiektu paymentProfile:
Parametr Typ Opis
id string(36) Identyfikator profilu UUID v4
merchantMid string(20) Identyfikator klienta
merchantCustomerId string(36) Identyfikator płatnika, dopuszczalne znaki: A-Za-z0-9 oraz myślnik (0x2D)
firstName string(100) Imię płatnika, dopuszczalne znaki: A-Za-z0-9#&_-"',./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne)
lastName string(100) Nazwisko płatnika, dopuszczalne znaki: A-Za-z0-9#&_-"',./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne)
maskedNumber string(16) Zamaskowany numer karty płatnika
month string(2) Ważność karty - miesiąc
year string(4) Ważność karty - rok
organization varchar(30) Organizacja karty płatnika
isActive integer(1) Aktywność profilu Oneclick/Recurring, dpouszczalne wartości: 1 (aktywny), 0 (nieaktywny)
profile string Typ profilu płatnika, dopuszczalne wartości: oneclick, recurring
statusCode string(24) Kod statusu transakcji Oneclick/Recurring
statusCodeDescription string(113) Opis kodu statusu transakcji Oneclick/Recurring

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": "pbl",
        "paymentMethodCode": "ipko"
    },
    "payment": {
        "id": "07980a69-a884-46f7-ad16-216c88a13b98",
        "title": "yourTitle",
        "amount": 100,
        "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.


Zmiany statusów transakcji należy dokonywać tylko gdy weryfikacja podpisu przebiegła poprawnie.

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": "yourTitle",
        "orderId": "yourOrderId",
        "paymentMethod": "pbl",
        "paymentMethodCode": "ipko"
    },
    "payment": {
        "id": "07980a69-a884-46f7-ad16-216c88a13b98",
        "title": "yourTitle",
        "amount": 100,
        "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": ""
    }
}

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


WAŻNE! Notyfikacje do raportów nie zawierają sygnatury.

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

Parametr Typ Opis
id string(36) Identyfikator raportu UUIDv4
status string Status raportu, dopuszczalne wartości: generated
fileExt string(5) Format raportu, dopuszczalne wartości: csv, owi1, mt940
created integer(10) Data utworzenia raportu
modified integer(10) Data modyfikacji raportu
url string(2083) Adres przekierowania

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.