Интеграция ЮKassa в PHP-магазин

Интеграция ЮKassa в PHP-магазин — приём оплаты на своём домене: карта, часто СБП и другие методы из кабинета ЮKassa. Скрипт создаёт платёж, покупатель уходит на форму, ваш endpoint получает вебхук и меняет статус заказа. Без вебхука вы живёте на «ну наверное оплатил» — так нельзя.

Корзина и checkout — магазин, оплата.

Что взять из кабинета ЮKassa

• shopId;
• секретный ключ (для боевого и тестового магазина — разные);
• настройки уведомлений: URL вебхука на ваш https;
• понимание, какие методы включены (карта, СБП…).

Ключи не коммитить в git и не светить во фронте. Только сервер. Тестовый режим гоняйте до первой рекламы.

URL, которые должны совпасть

1. Return URL — куда вернуть покупателя после оплаты (success/fail страницы магазина).
2. Webhook / notification URL — куда ЮKassa шлёт серверные события.
3. Домен строго https, сертификат не протухший.

Return URL не делает заказ оплаченным. Пользователь может закрыть вкладку. Статус paid — только после проверки уведомления (подпись/аутентичность по правилам API) и сверки суммы с заказом.

Идемпотентность статусов

Вебхук может прийти повторно. Обработчик обязан:

• найти заказ по payment_id / метаданным;
• сверить сумму и валюту;
• если уже paid — ответить успехом и выйти, не списывая остаток второй раз;
• логировать сырое событие для разбора конфликтов.

Списание склада — один раз при переходе в оплачен. Резервы до оплаты — отдельная политика; главное не смешивать две модели в одном товаре.

Связка с заказом в админке

В карточке заказа менеджер должен видеть:

• внутренний номер заказа;
• id платежа ЮKassa;
• статус оплаты;
• сумму;
• время перехода в paid.

Иначе сверка по утрам превращается в квест по двум кабинетам. Для частичной оплаты и возвратов заложите статусы заранее, даже если на старте «только полная оплата».

Типичные ошибки внедрения

1. Боевые ключи на тестовом домене и наоборот.
2. Webhook на http или на localhost «потом поменяем».
3. Создание платежа на сумму до промокода, а в заказе — после. Промо — здесь.
4. Доставка не включена в amount платежа. Доставка — тарифы.
5. Успешная страница показывает «оплачено» до вебхука — ложное чувство.
6. Нет обработки canceled: слот резерва висит вечно.

Минимальный тест

1. Товар 1 шт → checkout → тестовая оплата успех → заказ paid, остаток −1.
2. Повторная отправка вебхука (если можете) — остаток не −2.
3. Отмена/неуспех — заказ не paid, товар доступен.
4. Промокод −10% — amount платежа совпал с итогом.
5. Вариант размера — в заказе верный SKU. Варианты.

Ecommerce на своём хостинге — обзор, продукт — магазин PHP. ЮKassa закрывает эквайринг без самописной кассы; ваша зона ответственности — честные статусы, вебхук и сверка. Настройте ключи, URL и идемпотентность — и checkout перестаёт быть рулеткой.

Боевой запуск без драмы

Чеклист в день переключения с test на live:

1. В админке магазина прописаны боевые shopId и ключ.
2. В кабинете ЮKassa webhook указывает на боевой https URL.
3. Тестовый товар за 1–10₽ или возвратный чек — реальная оплата и возврат.
4. Заказ стал paid, остаток списался один раз.
5. Письмо/кабинет покупателя не обещают отправку до paid, если у вас предоплата.

Ключи теста после этого удаляю из конфига или храню только на стейдже. Путаница test/live — самая частая причина «клиент пишет, что оплатил, у нас пусто».

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

На старте я часто запрещаю частичную оплату: один заказ = один платёж на полную сумму. Возврат — из кабинета ЮKassa + статус в магазине refunded с комментарием менеджера. Если скрипт умеет инициировать refund API — ок, но кнопка только у роли админ. Автовозврат при отмене заказа без глаз человека опасен, пока нет чётких правил по комплектации.

• Не удаляйте заказ после оплаты — только статус.
• Храните payment_id вечно рядом с заказом.
• Расхождения суммы логируйте и алертите, не затирайте молча.

Раз в неделю сверка: paid в магазине vs обороты в ЮKassa. Нашли orphan-платёж без заказа — разбираете вручную; такое бывает при обрыве сессии после создания платежа. Для этого в метаданные платежа кладите order_id и не полагайтесь только на session.

Сообщения покупателю про оплату

Тексты на return URL пишите без паники: «если деньги списались, статус обновится в течение нескольких минут — не платите второй раз». Кнопка «оплатить снова» на том же заказе должна вести к тому же или новому платежу по правилам скрипта, не плодя дубли без контроля. В письме после paid — состав, сумма, что дальше с доставкой. Интеграция ЮKassa в PHP-магазин на этом этапе стыкуется с операционкой склада: нельзя обещать сборку в письме, если менеджер ещё не видит заказ.

Если используете СБП и карту — проверьте оба пути в тесте. Разные методы иногда по-разному ведут себя по скорости вебхука. Не считайте оплату завершённой по front-return. Серверный callback и идемпотентность — обязательная часть внедрения, не «фаза два». Тогда checkout перестаёт быть источником ночных сюрпризов в поддержке.

Окружения test и live

Держите стейдж с тестовыми ключами и прод с боевыми. Никогда не копируйте .env с live на демо-домен «на минуту посмотреть». Интеграция ЮKassa в PHP-магазин ломается чаще всего человеческим фактором, не API. В чеклисте деплоя — отдельный пункт «какой ключ сейчас в конфиге». Webhook URL после смены домена обновляйте в кабинете ЮKassa тем же днём.

Документируйте, кто имеет доступ к кабинету кассы. После увольнения — смена секрета. Логи вебхуков ротируйте, но не храните полные карточные данные (их там и не должно быть). Остаётся payment_id, сумма, статус, order_id — этого хватает для сверок и споров. Тогда эквайринг на своём домене остаётся под контролем, а не чёрным ящиком.