Способы оплаты

Откройте Пакеты → MiniShop3 → Настройки → Способы оплаты.

Для владельца магазина

1. Создайте способ оплаты: название, описание, логотип, активность.
2. Привяжите его к нужным доставкам. Без связки несвязанную пару всё равно удастся выбрать на шаге order/add — отказ приходит позже, при order/submit, с лексиконом ms3_order_err_payment_delivery.
3. Для оплаты «при получении» оставьте поле class пустым. Заказ получит выбранный payment_id.
4. Для онлайн-оплаты установите платёжное дополнение из каталога (например msp3YooKassa, mspTBank, msp3Sberbank) и укажите класс обработчика в поле class, как в инструкции пакета.
5. Проверьте переход после оплаты: ms3_order_success_page_id и страницу «Спасибо» с msGetOrder.

Наценка в поле price:

• 100: фиксированная сумма к заказу
• 3%: процент от стоимости корзины — доставка в базу комиссии не входит
• -5%: отрицательное значение работает как скидка

Допустимый процент — от −100 до 100. За пределами диапазона наценка обнуляется, а значение пишется в журнал ошибок.

Поля оплаты

Поле	Тип	Описание
name	string	Название способа оплаты
description	text	Описание для покупателя
price	string	Наценка (число или процент)
logo	string	Путь к изображению
position	int	Порядок сортировки
active	bool	Активность
class	string	PHP-класс обработчика платежа
properties	JSON	Настройки обработчика

Связь с доставкой

Связки правят с обеих сторон: на вкладке «Способы оплаты» в карточке доставки и на вкладке «Доставки» в карточке оплаты (POST и DELETE /api/mgr/payments/{id}/deliveries/{delivery_id}). Обе вкладки появляются только после первого сохранения записи. Типичные наборы:

• Самовывоз: наличные, карта при получении
• Курьер: наличные, карта, онлайн
• Почта: наложенный платёж, онлайн

Обработчики платежей

Встроенных обработчиков нет: онлайн-оплату даёт платёжное дополнение из каталога или собственный класс. Класс наследуется от абстрактной Payment и указывается в карточке способа оплаты; готовые платёжные сервисы описаны в документации дополнений. Обязательны только send() и receive():

<?php
namespace MyComponent\Payment;

use MiniShop3\Controllers\Payment\Payment;
use MiniShop3\Model\msOrder;

class MyPayment extends Payment
{
    public function send(msOrder $order): array
    {
        // Создать платёж у провайдера; return_url: ms3_order_success_page_id
        // Платёжная запись способа оплаты: $this->config['payment']
        return [
            'success' => true,
            'data' => ['payment_link' => '...'],
        ];
    }

    public function receive(msOrder $order): array
    {
        // Webhook / callback провайдера
        return ['success' => true, 'message' => 'Payment received'];
    }
}

Конструктор переопределять не нужно. Базовый Payment::__construct(MiniShop3 $ms3, array $config = []) прокидывает $this->modx и $this->ms3, а сервис создаёт обработчик как new $class($ms3, ['payment' => $payment]). Если нужны ключи из properties, вызывайте parent::__construct($ms3, $config) в своём конструкторе. Методы getCost() (наценка по полю price), getPaymentLink() и getOrderHash() (HMAC-SHA256 по ms3_payment_secret) уже реализованы в базе, переопределяйте только свою логику.

Регистрация в поле class:

MyComponent\Payment\MyPayment

Секреты платёжного сервиса задают в properties (JSON) карточки оплаты. Через интерфейс настроек это поле не редактируется — ни в карточке оплаты, ни в карточке доставки его нет: записывайте значение через Manager API (PUT /api/mgr/payments/{id}), со страницы платёжного дополнения или прямо в БД.

{
  "shop_id": "123456",
  "secret_key": "live_xxx...",
  "test_mode": false
}

В коде: $this->config['payment']->get('properties').

Уведомления об оплате (webhook / callback)

В ядре есть штатный приёмник: POST /api/v1/payment/webhook/{payment_method_id}. Маршрут публичный — TokenMiddleware его пропускает, подпись проверяет сам обработчик.

Класс оплаты реализует PaymentWebhookHandlerInterface с двумя методами: verifyWebhook() — проверка подлинности по сырому телу, разобранному payload и заголовкам, и parseWebhook() — разбор в PaymentWebhookEvent. Для HMAC в базовом классе есть Payment::verifyWebhookHmac(), секрет берётся из properties карточки оплаты по ключам secret, secret_key, webhook_secret, а если их нет — из системной настройки ms3_payment_secret. Применяет событие PaymentLifecycleService (сервис ms3_payment_lifecycle).

Часть платёжных дополнений по-прежнему держит собственный приёмник (webhook.php / callback.php в assets/components/{ns}/) — смотрите документацию конкретного сервиса (msp3YooKassa, mspTBank и т.д.).

Класс оплаты реализует send() и приём уведомления, по полученному уведомлению он меняет статус заказа. Ссылка на оплату в письмах и msGetOrder строится через PaymentLinkResolver.

API

Доставки и оплаты в черновике заказа

Публичные списки (без токена): GET /api/v1/delivery/list, GET /api/v1/payment/list. Отдельного GET /api/v1/order/payments нет.

Черновик:

GET /api/v1/order/get

В data.order лежат поля заказа, в том числе delivery_id / payment_id и address_*. Смена способа: POST /api/v1/order/add или POST /api/v1/order/set с телом-обёрткой {"fields": {"payment_id": 2}}. Фронтенд на Fenom может отображать выбор через msOrder.

Стоимость оплаты

Эндпоинт считает комиссию по способу оплаты, который уже выбран в черновике, и параметры запроса не читает. Чтобы узнать стоимость другого способа, сначала запишите его через order/add или order/set.

GET /api/v1/order/cost/payment

Ответ:

{
    "success": true,
    "data": {
        "cost": 150.00
    }
}

Полный расчёт (корзина + доставка + оплата): GET /api/v1/order/cost. Карта Web API: Checkout.

Ссылка на оплату (payment_link)

На странице «спасибо» и в письмах URL оплаты формирует PaymentLinkResolver (ms3_payment_link_resolver):

• в msGetOrder — параметр payStatus (CSV статусов);
• в уведомлениях — настройка ms3_payment_link_statuses (CSV id статусов; скрытая — в Системных настройках не объявлена, задаётся напрямую в БД или кодом), если пуста, берётся ms3_status_new;
• ссылка не показывается для финальных статусов и статуса «оплачен».

Обработчик способа оплаты должен вернуть URL из метода оплаты (см. пример send() выше). Подробнее: msGetOrder.