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

Модуль інтеграції платіжної системи Hutko для інтернет-магазинів на базі MODX Revolution та компонента miniShop2.

Особливості

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

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

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

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

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

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

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

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

Створення системного налаштування:

Перейдіть до Системні налаштування (System -> System Settings).
Натисніть Створити нове налаштування.
Заповніть поля:
- Ключ: ms2_hutko_payment_ID_config (де ID — це ідентифікатор вашого методу оплати з кроку 2. Наприклад, якщо ID методу оплати = 3, ключ має бути ms2_hutko_payment_3_config).
- Тип запису: Текстова область (textarea)
- Простір імен: minishop2 (або core)
- Значення: Вставте 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 на одному сайті (наприклад, для прийому оплат у різних валютах, на різні ФОП/Компанії, або для різних способів доставки).

Як це зробити:

Створіть перший метод оплати в miniShop2 (наприклад, ID 3 — "Оплата від ФОП 1").
Створіть другий метод оплати в miniShop2 (наприклад, ID 4 — "Оплата від ТОВ 2").
Створіть два різних системних налаштування:
- Ключ: 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:

У системному налаштуванні ms2_hutko_payment_ID_config замініть дані на:

{
  "merchant_id": "1700002",
  "secret_key": "test"
}

Зробіть тестове замовлення.
Після завершення тестування не забудьте змінити ці дані на ваші робочі (бойові) ключі!

6. Callback (Webhooks)

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

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

При успішній оплаті модуль:

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

7.8 KiB Raw Blame History Unescape Escape