feat(core): add payment attempt lifecycle and webhook callback by Ibochkarev · Pull Request #604 · modx-pro/MiniShop3

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev · 2026-08-19T04:07:29Z

Описание

У заказа был только status_id. Async-провайдеру некуда было сохранить external_id, и в core не было общего webhook-входа.

Появились таблицы ms3_payment_attempts и ms3_payment_attempt_events (уникальные (payment_method_id, provider, external_id) и (attempt_id, event_type, provider_event_id)), сервис PaymentLifecycleService (DI ms3_payment_lifecycle) и публичный POST /api/v1/payment/webhook/{payment_method_id} без customer token. Тело только raw JSON, не $_POST. Невалидный JSON даёт 400, необработанный Throwable — 500 и запись в лог.

Смена статуса заказа идёт только через OrderStatusChanger. Провайдеры не пишут status_id. Повторный успешный callback идемпотентен: unique event в одной транзакции с UPDATE попытки (writeWithEvent), затем ensure(). Если заказ уже в целевом статусе, ensure() не вызывает change() — replay paid на fixed-статусе не даёт 409.

Статусы попытки: pending, authorized, paid, failed, cancelled, refunded, partially_refunded. DefaultPayment attempt не создаёт: в send() нет payment_id / external_id. Политики ms3_payment_on_failed_status и ms3_payment_on_refunded_status (по умолчанию 5, 0 оставляет заказ).

getPaymentLink идёт через PaymentService::resolvePaymentLink: ссылка открытой попытки этого метода (pending/authorized), иначе send() + initiate(). Если initiate() после успешного send() упал, checkout получает success => false и ms3_err_payment_attempt_record. apply() и refund() коммитят одинаково: writeWithEvent → ensure().

Webhook paid / refunded / partially_refunded требуют non-empty externalId и paid ещё amount. Если в webhook есть currency, она должна совпасть с attempt. Paid amount = attempt amount, attempt amount = текущий order.cost. Refund требует provider event id. Over-refund не режется молча. external_id чужого метода не закрывает текущую попытку. Attempt на callback не создаётся с нуля. resolveAttempt только читает: external_id пишется в commit.

Секреты msPayment.properties убраны из OrdersPageService, ms3_get_order и писем (PaymentPublicFields). Эталонный HMAC: PaymentWebhookHmac и Payment::verifyWebhookHmac() (secret из propertiessecret / secret_key / webhook_secret, затем ms3_payment_secret). Конкретный эквайер в этот PR не входит.

Тип изменений

Новая функциональность (non-breaking change)

Связанные Issues

Closes#590

Как это было протестировано?

Локальный CI-гейт (без полной установки MODX/MySQL):

cd core/components/minishop3
composer ci:php
# php -l 648 files, exit 0# smoke 90, exit 0# PHPUnit 294 tests, 708 assertions, 9 skipped (@group mysql without DSN), 2 deprecations, exit 0
composer stan:prepare && composer stan
# [OK] No errors, exit 0

Vue не менялся, npm run lint:ci не запускался.

Автоматические тесты (composer ci:php, composer stan)
Ручное тестирование webhook с реальным провайдером
Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

MiniShop3: ветка feat/issue-590-payment-lifecycle от beta (коммиты 11721446, e7dcb7b0, b2ccc755)
MODX: не поднимался
PHP: 8.4.17

Скриншоты (если применимо)

N/A, backend/API.

Чеклист

Код соответствует стилю проекта
Добавлены/обновлены комментарии в сложных местах
Изменения не ломают существующую функциональность (PaymentProviderInterface и DefaultPayment без изменений контракта send/receive)
Лексиконы добавлены на двух языках (ru/en)
PHPStan проходит без новых ошибок (composer stan)
ESLint (npm run lint:ci) — N/A, Vue не тронут
CHANGELOG.md — не трогал, запись на релиз

Дополнительные заметки

Контракт провайдера: PaymentWebhookHandlerInterface::verifyWebhook($rawBody, $payload, $headers, $method) + PaymentLifecycleService. Старые провайдеры с собственным webhook продолжают работать. Новый вход opt-in.

Fenom-чанки, которые читали payment.properties, больше не получают секреты. Это цель AC.

Follow-up b2ccc755 закрывает blocker/high из ревью #604: replay на fixed, атомарный commit, currency, stale cost, externalId для финансовых событий, read-only resolveAttempt, без partialRefund().

Вне scope этого issue: конкретный эквайер, 3DS, UI попыток в менеджере, timeout pending, #569 payment/list.

Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

feat(core): add payment attempt lifecycle and webhook callback
1172144
Async providers need a payment attempt distinct from msPayment and order status, plus an idempotent core webhook that maps events through OrderStatusService.

Ibochkarev added the enhancement New feature or request label Aug 19, 2026

fix(core): route payment links and unify attempt commit
e7dcb7b
Checkout now fails when initiate() cannot record an attempt after send(), and getPaymentLink goes through PaymentService instead of a second gateway call.

Ibochkarev requested a review from biz87 August 19, 2026 04:38

fix(core): make paid webhook replay succeed on fixed order status
b2ccc75
Replay no longer re-runs change() when the order is already paid, and attempt fields plus the idempotency event persist in one write. Financial callbacks now require matching currency, current order cost, and externalId.

Ibochkarev mentioned this pull request Aug 22, 2026
Core: Payment Operations поверх Payment Attempts #626
Open