Интеграция ЮKassa с интернет-магазином: как связать платёж с заказом
Покупатель оплатил заказ, а в админке по-прежнему написано «Ожидает оплаты». Если отправить ему новую ссылку, можно получить второй платёж за ту же покупку. Сначала нужно найти первую операцию и понять, на каком участке разошлись данные: в ЮKassa, на сайте или при передаче в 1С.
С чего начать, если покупатель уже оплатил
Найдите заказ в админке и связанный с ним платёж в кабинете ЮKassa. Сверьте идентификатор операции, сумму и время. У одного заказа могут быть несколько попыток оплаты, поэтому одного совпадения по номеру заказа недостаточно. Скриншот банковского приложения поможет начать поиск; решение об отгрузке должно опираться на подтверждённое состояние платежа.
В истории платежей ЮKassa можно открыть подробности операции и перейти к её логам. На официальном примере ниже платёж оплачен, а чек не доставлен в облачную кассу. У этих двух событий разные результаты. Повторно брать деньги с покупателя из-за ошибки чека не нужно.
В ответе API состояние платежа обозначается техническим кодом. Его полезно показывать разработчику при обращении в поддержку:
| Статус ЮKassa | Что произошло | Что проверить в магазине |
|---|---|---|
pending | Платёж ещё не завершён. | Не помечен ли заказ оплаченным раньше времени. |
waiting_for_capture | Деньги авторизованы и ожидают списания. | Кто подтверждает списание и отслеживает срок в expires_at. |
succeeded | Платёж успешно завершён. | Совпадают ли сумма и заказ; записан ли результат на сайте. |
canceled | Эта попытка оплаты отменена. | Нет ли другой успешной попытки по тому же заказу. |
Если ЮKassa подтверждает успешный платёж, а сайт его не учёл, разбирать нужно обработку результата. Если сайт уже записал оплату, но 1С её не получила, проверяют обмен с учётной системой. Это разные задачи, с разными журналами ошибок и способами восстановления.
Сумму сверяют с условиями, сохранёнными при создании конкретной попытки оплаты. После этого менеджер мог убрать товар или пересчитать доставку. Текущая сумма изменённого заказа уже не объяснит, сколько покупатель заплатил первоначально. Для проверки нужен сохранённый состав расчёта, включая скидку и доставку.
Возврат покупателя на сайт не подтверждает оплату
Адрес return_url нужен, чтобы вернуть человека из платёжного интерфейса в магазин. По документации ЮKassa, переход на него возможен и при успешной оплате, и при ошибке. Покупатель также может закрыть вкладку и вообще не вернуться.
Поэтому обработку платежа связывают с сервером магазина. ЮKassa отправляет ему уведомление об изменении состояния. Сервер проверяет операцию и записывает результат в заказ. Эта часть должна работать при закрытом браузере покупателя.
В публичной справке ЮKassa настройки уведомлений выглядят так. Адрес получателя на иллюстрации относится к примеру из справки; для своего магазина указывают адрес собственного обработчика. Набор событий выбирают под используемую схему оплаты.
ЮKassa ожидает ответ HTTP 200. При другом коде она повторяет доставку в течение 24 часов с момента события. Эти правила описаны в разделе входящих уведомлений. Получение сообщения нужно подтверждать после того, как система надёжно сохранила его для обработки. Если ответить раньше, а затем потерять данные при сбое, сайт останется без результата операции.
При проектировании обработчика мы рекомендуем сверять текущее состояние платежа через API ЮKassa, его принадлежность магазину, сумму и валюту сохранённой попытки оплаты. Затем сохранять изменение вместе с заданиями для следующих действий: уведомить менеджера, передать оплату в 1С. Временная недоступность 1С не должна стирать уже полученное подтверждение платежа.
Для пропущенных событий нужна периодическая сверка незавершённых операций с ЮKassa. Она позволит найти успешную оплату, даже если магазин долго не принимал уведомления. Если к моменту сверки заказ уже отменили и резерв товара снят, следует показать расхождение сотруднику. Автоматически отправлять такой заказ на сборку опасно: товара может уже не быть.
Один заказ может иметь несколько попыток оплаты
Покупатель дважды нажал кнопку. Другой вариант: сайт отправил запрос, но не дождался ответа. В обоих случаях приходится выяснять, была ли создана операция. Если на каждый повтор создавать новый платёж, две ссылки могут привести к двум успешным списаниям.
Для повторения одного запроса в API ЮKassa предусмотрен Idempotence-Key. Смысл этого ключа прост: «это всё ещё та же операция». Запрос с теми же данными и ключом обрабатывается как повторный. Защита действует 24 часа; после этого такой запрос будет считаться новым. Правила приведены в формате взаимодействия с API.
В истории попыток на сайте сохраняют связь заказа с платежами ЮKassa и результат обработки каждой операции. Если клиент повторяет оплату после ошибки, менеджер видит обе попытки и понимает, какая завершилась успешно. При повторе уведомления обработчик находит уже учтённый платёж: второй заказ не появляется, оплаченную сумму повторно не прибавляют. Сборка заказа при этом не запускается заново.
Отдельный случай для приёмки: по одному заказу всё же появились два разных успешных платежа. Система должна обнаружить лишнюю оплату и передать её сотруднику на разбор. Нельзя просто проигнорировать второй платёж: деньги покупателя уже приняты.
Частичный возврат: расчёт на одном заказе
Для проверки возьмём условный заказ № 2041. В нём два товара за 6 900 ₽ и 4 100 ₽, доставка стоит 350 ₽. Покупатель заплатил 11 350 ₽. После оплаты второй товар отменили. Для этого учебного расчёта условимся, что доставка остаётся 350 ₽.
| Действие | Деньги | Состояние заказа |
|---|---|---|
| Получена оплата | Принято 11 350 ₽. | Оба товара и доставка оплачены. |
| Отменён второй товар | Предстоит вернуть 4 100 ₽. | Товар исключён из отгрузки. Возврат ещё нужно выполнить. |
| Создана заявка на возврат | 4 100 ₽ запрошены к возврату. | Менеджер видит незавершённую операцию. |
| Возврат подтверждён | Из принятых денег осталось 7 250 ₽. | 6 900 ₽ за оставшийся товар и 350 ₽ за доставку учтены. |
В админке нужно сохранить, за какую позицию возвращается сумма, кто начал операцию и чем она закончилась. После зависшего экрана сотрудник должен сначала увидеть состояние созданного возврата. Повторное нажатие не должно незаметно отправить ещё одну заявку на ту же сумму.
В интерфейсе ЮKassa после отправки заявки показано отдельное подтверждение. Оно сообщает об отправке, а завершение возврата нужно проверить по результату операции.
По API возврат имеет собственный идентификатор и связан с исходным платежом. При работе с ним проверяют поддержку частичного возврата выбранным способом оплаты и уже возвращённую сумму. Подробности есть в инструкции ЮKassa по возвратам.
Технический статус успешного платежа succeeded финальный. Возврат учитывается отдельно, поэтому одного поля «Оплачен / Не оплачен» для заказа недостаточно. В нашем примере после возврата заказ остаётся оплачен на 7 250 ₽. Если переключить его целиком в «Не оплачен», менеджер может повторно запросить деньги за оставшийся товар.
Что происходит с чеком и передачей в 1С
В примере из истории платежей выше ошибка касалась чека. При интеграции со сторонней онлайн-кассой ЮKassa поддерживает несколько схем передачи данных. В схеме «Платёж и чек одновременно» неуспешная регистрация чека не отменяет платёж. В других схемах порядок отличается. Поэтому диагноз «ошибка чека значит, оплаты нет» нельзя применять ко всем заказам. Описание схем в документации ЮKassa.
До подключения определите, какая система отправляет данные для чеков и где сотрудник увидит сбой. Если эту работу одновременно выполняют модуль сайта и доработка в 1С, нужно проверить, не отправляют ли они данные по одному расчёту повторно. Реквизиты чеков и порядок их формирования согласуют с бухгалтером под вашу схему продаж; разработчику передают эти требования до настройки интеграции.
В обмене с 1С полезно разделить три результата: сайт получил подтверждение оплаты, сформировал задание на передачу, учётная система приняла данные. Тогда в карточке можно показать «Оплачен, передача в 1С задержана». Сотрудник увидит, какую задачу нужно решить, и не станет снова отправлять покупателю ссылку на оплату.
После восстановления обмена повторная отправка должна обновить нужный документ по сохранённой связи. Создание нового заказа при каждом повторе приведёт к дублям в учёте. Вопросы о составе обмена разобраны отдельно в статье об интеграции интернет-магазина с 1С.
Что должен видеть менеджер
Для разбора расхождения сотруднику нужны сумма заказа, принятые платежи, возвраты и оставшаяся сумма оплаты. Рядом стоит показывать идентификаторы операций и время последнего обновления. Техническая ошибка должна объяснять, что задержано: получение статуса, запись в заказ или передача в 1С.
В кабинете ЮKassa логи событий для интеграций по API доступны за последние семь суток. В них можно найти запрос и ответ сервиса. Для сайта нужен свой журнал обработки, чтобы связать эти сведения с заказом и действиями сотрудников. Если проблему заметили позже, чужой кабинет уже может не содержать нужных записей.
Секретный ключ, полные платёжные реквизиты и лишние персональные данные в рабочем журнале не нужны. Права тоже стоит разделить: сотруднику может быть разрешён просмотр операции, но запрещено создавать возврат. Сам возврат должен оставлять запись о пользователе, сумме и основании.
Как принять интеграцию перед запуском
Основные сбои проверяют в тестовом магазине ЮKassa с отдельными уведомлениями. Подготовьте заказ с вашей доставкой и скидкой, подключите тестовый обмен с 1С. Так проверка охватит расчёт итоговой суммы и обработку заказа после оплаты.
На приёмке откройте заказ как обычный менеджер. Проведите оплату и закройте вкладку покупателя до возвращения в магазин. Затем повторите уведомление, отключите обмен с 1С и выполните частичный возврат. После каждого действия сверяйте операции и суммы. Для условного заказа из расчёта итог после возврата должен остаться 7 250 ₽; повтор сообщения эту сумму не меняет.
Скачать таблицу приёмки интеграции ЮKassa. В ней 12 сценариев с ожидаемым результатом и полями для фиксации операции. Технические повторы и имитацию сбоев выполняет разработчик в тестовой среде.
Тестовые операции не проверяют реальные расчёты по договору. Контрольную настоящую оплату после переключения организуют отдельно с владельцем магазина и учитывают в бухгалтерии. Включать боевой режим нужно после согласования такой проверки.
Что влияет на стоимость подключения
Для готового магазина с поддерживаемым модулем может хватить его настройки и проверки. Доработка нужна, когда стандартное решение не покрывает ваш процесс: частичную отмену, несколько попыток оплаты, ручное подтверждение списания или обмен с 1С. Перечень возможностей проверяют для конкретной версии модуля.
В оценке стоит выделить подключение платёжного интерфейса, обработку результатов, возвраты, передачу в учёт и проверку сбоев. Отдельно фиксируют, кто исправляет ошибку после запуска и как сотрудник восстановит заказ без повторного списания. Срок и стоимость зависят от действующего кода и согласованных сценариев.
Если в магазине уже расходятся платежи и заказы, передайте в CAPS адрес сайта, название CMS, описание сбоя и время проблемной операции. Данные покупателя можно скрыть; секретные ключи для первичного разбора не нужны. По этим сведениям определим, какой участок интеграции проверять и что потребуется для оценки доработки.
