Add README.md
This commit is contained in:
122
README.md
Normal file
122
README.md
Normal file
@@ -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`.
|
||||
Reference in New Issue
Block a user