# 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`.
> info
> 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**
> info
> 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 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
> info
> 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](#topic-notyfikacje#topic-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
> info
> 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
```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": 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:
```json
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
```json
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.
> info
> 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`:
```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:
```javascript
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](https://imoje.ing.pl) 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"
}
```
> info
> 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.