122 lines
7.8 KiB
Markdown
122 lines
7.8 KiB
Markdown
# Платіжний модуль 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`. |