From 74e31c19157c56d146d338f949015d8d3b25e8fe Mon Sep 17 00:00:00 2001 From: panariga Date: Mon, 9 Mar 2026 14:21:43 +0200 Subject: [PATCH] Add README.md --- README.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3fb0a8a --- /dev/null +++ b/README.md @@ -0,0 +1,122 @@ +# Платіжний модуль 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`. \ No newline at end of file