# 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.
> info
> Notifications are sent from IP addresses in the following ranges:
**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
> Notifications are sent to the default HTTP (80) and HTTPS (443) ports.
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.
> info
> If the merchant's server returns a 200 OK status, or the notification is not received by the end of the entire cycle, imoje servers will stop resending the notification.
If **two identical notifications** are received from imoje servers, the first one should be handled in accordance with the section [notification signature verification method](#topic-notifications#topic-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
> info
> The `payment` object will be the only object sent when the payment link expires or is manually cancelled.
## Notification parameters
#### Parameters for the `transaction` object:
| Parameter | Type | Description |
|------------------------|-------------|-------------------------------------------------------|
| `id` | string(36) | Transaction identifier `UUID v4` |
| `type` | string | Type of transaction, **allowed values**: `sale`, `refund` |
| `status` | string | Transaction status, **allowed values**: `new`, `pending`, `settled`, `cancelled`, `rejected` |
| `source` | string | Transaction source, **allowed values**: `api`, `web` |
| `created` | integer(10) | Transaction creation date |
| `modified` | integer(10) | Transaction modification date |
| `notificationUrl` | varchar(300)| Notification address |
| `serviceId` | string(36) | Service identifier `UUID v4` |
| `amount` | integer(9) | Transaction amount, **maximum value**: 999999999 |
| `currency` | string(3) | Transaction currency in `ISO 4217` |
| `title` | string(255) | Order title, **allowed characters**: A-Za-z0-9#&_-"',./ and space character(0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritics) |
| `orderId` | string(100) | Order number, **allowed characters**: A-Za-z0-9#_-./ and space character(0x20) and characters from the UNICODE range 00C0 - 02C0 (including Polish diacritics) |
| `paymentMethod` | string | Order fulfilment method |
| `paymentMethodCode` | string | Indication of payment channel |
| `statusCode` | string(24) | Card transaction status code |
| `statusCodeDescription`| string(113) | Card transaction status code description |
#### Parameters for the `payment` object:
| Parameter | Type | Description |
|------------------------|-------------|-------------------------------------------------------|
| `id` | string(36) | Order identifier `UUID v4` |
| `title` | string(255) | Order title, **allowed characters**: A-Za-z0-9#&_-"',./ and space character(0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritics) |
| `amount` | integer(9) | Order amount, **maximum value**: 999999999 |
| `status` | string | Order status, **allowed values**: `new`, `pending`, `settled`, `cancelled`, `rejected` |
| `created` | integer(10) | Order creation date |
| `orderId` | string(100) | Order number, **allowed characters**: A-Za-z0-9#_-./ and space character(0x20) and characters from the UNICODE range 00C0 - 02C0 (including Polish diacritics) |
| `currency` | string(3) | Order currency in `ISO 4217` |
| `modified` | integer(10) | Order modification date |
| `serviceId` | string(36) | Service identifier `UUID v4` |
| `notificationUrl` | varchar(300)| Notification address |
| `ipksef` | string | KSeF payment identifier |
#### Parameters for the `action` object:
| Parameter | Type | Description |
|------------------------|-------------|-------------------------------------------------------|
| `type` | string | Redirection type, **allowed values**: `redirect`, `transfer` |
| `url` | string(2083)| Redirection address |
| `method` | string | Redirection method, **allowed values**: `POST`, `GET` |
| `contentType` | varchar(100)| Data format type |
| `contentBodyRaw` | text | Redirection parameters |
| `ban` | string(26) | Bank account number, **returned for Wire Transfer payment method** |
#### Parameters for the `paymentProfile` object:
| Parameter | Type | Description |
|------------------------|-------------|-------------------------------------------------------|
| `id` | string(36) | Profile identifier as `UUID v4` |
| `merchantMid` | string(20) | Merchant identifier |
| `merchantCustomerId` | string(36) | Customer identifier, **allowed values**: A-Za-z0-9 and dash (0x2D) |
| `firstName` | string(100) | Customer first name, **allowed values**: A-Za-z0-9#&_-"',./ and space character(0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritics) |
| `lastName` | string(100) | Customer last name, **allowed values**: A-Za-z0-9#&_-"',./ and space character(0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritics) |
| `maskedNumber` | string(16) | Masked customer card number |
| `month` | string(2) | Card validity - month |
| `year` | string(4) | Card validity - year |
| `organization` | varchar(30) | Customer card organization |
| `isActive` | integer(1) | Oneclick/Recurring profile activity, **allowed values**: `1` (active), `0` (inactive) |
| `profile` | string | Customer profile type, **allowed values**: `oneclick`, `recurring` |
| `statusCode` | string(24) | Oneclick/Recurring transaction status code |
| `statusCodeDescription`| string(113) | Oneclick/Recurring transaction status code description |
## Example content of the notification BODY
```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": "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": ""
}
}
```
## Notification header content
Additionally, the following parameters are included in HTTP headers:
```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}"
```
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
```json
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.
> info
> Transaction statuses should only be changed once the signature has been successfully verified.
### 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`:
```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. 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:
```javascript
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](https://imoje.ing.pl), 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"
}
```
> info
> IMPORTANT! Notifications for reports do not contain signatures.
The notification may consist of the following parameters:
| Parameter | Type | Description |
|------------|--------------|------------------------------------------------------------------|
| `id` | string(36) | Report identifier `UUIDv4` |
| `status` | string | Report status, **acceptable values**: `generated` |
| `fileExt` | string(5) | Report format, **acceptable values**: `csv`, `owi1`, `mt940`|
| `created` | integer(10) | Date of report creation |
| `modified` | integer(10) | Report modification date |
| `url` | string(2083) | Redirect address |
## 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.