# Платіжний модуль Hutko для miniShop2 (MODX Revolution)

Модуль інтеграції платіжної системи [Hutko](https://hutko.org/) для інтернет-магазинів на базі MODX Revolution та компонента miniShop2.

## Особливості
* Автоматична генерація посилання на оплату.
* Автоматична зміна статусу замовлення при успішній оплаті (через Callback).
* Передача даних про кошик (товари, кількість, ціни, вартість доставки).
* Передача даних клієнта для фіскалізації/резервації.
* **Підтримка кількох конфігурацій (мерчантів)** на одному сайті.

---

## 1. Встановлення файлів

Скопіюйте файли з репозиторію у корінь вашого сайту, зберігаючи структуру директорій:

1. `hutko.php` -> `assets/components/minishop2/payment/hutko.php`
2. `hutko.class.php` -> `core/components/minishop2/custom/payment/hutko.class.php`

---

## 2. Додавання методу оплати в miniShop2

1. В адмін-панелі MODX перейдіть до **Магазин** (miniShop2) -> **Налаштування** -> вкладка **Оплата**.
2. Натисніть **Створити** (або "Додати").
3. Заповніть поля:
   * **Назва:** Hutko (або "Оплата карткою", "Оплата онлайн" тощо)
   * **Клас обробника:** `Hutko`
   * **Активний:** Так
4. Збережіть метод оплати.
5. **Важливо:** Зверніть увагу на **ID** щойно створеного методу оплати (наприклад, `2`, `3` або `4`). Цей ID знадобиться для налаштування конфігурації.

---

## 3. Налаштування конфігурації (JSON)

Платіжний модуль використовує системні налаштування MODX для зберігання конфігурації у форматі JSON. Це дозволяє гнучко налаштовувати модуль без редагування коду.

### Створення системного налаштування:
1. Перейдіть до **Системні налаштування** (System -> System Settings).
2. Натисніть **Створити нове налаштування**.
3. Заповніть поля:
   * **Ключ:** `ms2_hutko_payment_ID_config` (де **ID** — це ідентифікатор вашого методу оплати з кроку 2. Наприклад, якщо ID методу оплати = `3`, ключ має бути `ms2_hutko_payment_3_config`).
   * **Тип запису:** `Текстова область` (textarea)
   * **Простір імен:** `minishop2` (або `core`)
   * **Значення:** Вставте JSON-код (див. приклад нижче).

### Приклад конфігурації (JSON):

```json
{
  "merchant_id": "ВАШ_MERCHANT_ID",
  "secret_key": "ВАШ_SECRET_KEY",
  "currency": "UAH",
  "paid_status_id": 2,
  "payment_with_delivery": true,
  "delivery_code": "Shipping_001",
  "delivery_name": "Доставка",
  "order_description": "Оплата замовлення #"
}
```

### Опис параметрів конфігурації:

| Параметр | Опис | Значення за замовчуванням |
| :--- | :--- | :--- |
| `merchant_id` | ID вашого мерчанта в системі Hutko. | `""` *(обов'язково вказати)* |
| `secret_key` | Секретний ключ для підпису запитів. | `""` *(обов'язково вказати)* |
| `currency` | Валюта платежу. | `"UAH"` |
| `paid_status_id` | ID статусу замовлення в ms2, який буде встановлено після успішної оплати. | `2` *(Зазвичай 2 = "Оплачено")* |
| `payment_with_delivery` | Чи включати вартість доставки у загальну суму оплати (true/false). | `true` |
| `delivery_code` | Артикул/код послуги доставки для чека. | `"Shipping_001"` |
| `delivery_name` | Назва послуги доставки для чека. | `"Shipping"` |
| `order_description` | Префікс призначення платежу (до нього автоматично додасться номер замовлення). | `"Оплата замовлення #"` |
| `success_url` | URL, куди повернеться клієнт після оплати. | Головна сторінка сайту |

*(Будь-який параметр можна пропустити в JSON, тоді модуль використає значення за замовчуванням).*

---

## 4. Використання кількох конфігурацій (Мультиакаунтність)

Модуль спроєктовано так, що ви можете підключити **декілька різних акаунтів Hutko** на одному сайті (наприклад, для прийому оплат у різних валютах, на різні ФОП/Компанії, або для різних способів доставки).

**Як це зробити:**
1. Створіть перший метод оплати в miniShop2 (наприклад, ID `3` — "Оплата від ФОП 1").
2. Створіть другий метод оплати в miniShop2 (наприклад, ID `4` — "Оплата від ТОВ 2").
3. Створіть два **різних** системних налаштування:
   * Ключ: `ms2_hutko_payment_3_config` (зі своїм `merchant_id` та `secret_key` для ФОП 1).
   * Ключ: `ms2_hutko_payment_4_config` (з іншими `merchant_id` та `secret_key` для ТОВ 2).

Коли покупець обирає певний метод оплати, модуль автоматично підтягує відповідний JSON конфіг на основі ID обраного методу.

---

## 5. Тестовий режим (Sandbox)

Для тестування оплат без використання реальних коштів, використовуйте тестові дані Hutko:

1. У системному налаштуванні `ms2_hutko_payment_ID_config` замініть дані на:
```json
{
  "merchant_id": "1700002",
  "secret_key": "test"
}
```
2. Зробіть тестове замовлення.
3. Після завершення тестування **не забудьте змінити ці дані на ваші робочі (бойові) ключі!**

---

## 6. Callback (Webhooks)

Скрипт `assets/components/minishop2/payment/hutko.php` слугує Endpoint'ом для прийому сповіщень (вебхуків) від сервера Hutko про зміну статусу платежу.

Модуль автоматично формує та передає цей URL в Hutko під час створення платежу (параметр `server_callback_url`). Вам **не потрібно** прописувати його вручну в кабінеті Hutko, все відбувається автоматично.

При успішній оплаті модуль:
1. Перевіряє валідність цифрового підпису (`signature`).
2. Перевіряє, чи сума платежу збігається з сумою замовлення.
3. Змінює статус замовлення в MODX на вказаний у `paid_status_id`.