Как подключить ЮKassa к интернет-магазину и принять интеграцию
Что подготовить для подключения ЮKassa, как разделить тестовые и рабочие настройки, выбрать путь формирования чеков и проверить готовность оплаты.
Подключение ЮKassa состоит из трёх связанных работ: оформить отношения с провайдером, настроить обмен с магазином и определить, кто формирует фискальные чеки. Готовая кнопка оплаты подтверждает только часть результата. До рабочего запуска должны согласованно действовать заказ, платёж, чек и обработка ошибок.
Ниже — порядок для магазина, который уже выбрал ЮKassa. Общую схему платежей и выбор решения объясняет руководство по онлайн-оплате. Здесь результатом будет лист приёмки конкретного подключения с разделёнными тестовыми и рабочими настройками.
Что подготовить до интеграции
Уточните статус продавца, виды товаров, сайт, реквизиты, контакт для подключения и расчётный счёт по требованиям выбранного договора. На сайте должны быть достоверные сведения о товарах, цене, способах получения, продавце и возврате. Проверка заявки ЮKassa не заменяет проверку законности самого ассортимента.
В личном кабинете создайте магазин, заполните заявку и выполните требуемые провайдером шаги проверки и заключения договора. Состав запрашиваемых сведений зависит от роли и деятельности; не ориентируйтесь на обещание одинакового срока одобрения для всех. Тестовый магазин позволяет начать техническую проверку раньше, но не означает готовность принимать рабочие деньги.
Выберите способ подключения. Если платформа поддерживает готовый модуль, сначала уточните его версию, доступные способы оплаты, уведомления и путь передачи чековых данных. При подключении по API эти обязанности реализует разработчик. Модуль сокращает настройку, но не освобождает магазин от приёмки результата.
Разделите тестовые и рабочие параметры
| Что проверить | Тестовая среда | Рабочая среда |
|---|---|---|
| Магазин и параметры доступа | Идентификатор и секрет тестового магазина | Параметры одобренного рабочего магазина |
| Адрес уведомлений | Тестовый обработчик и журнал | Доступный рабочий обработчик |
| Заказы | Помечены как тестовые, без реальной отгрузки | Связаны с фактическими покупками |
| Чеки | Доступный режим имитации | Выбранная действующая схема фискализации |
| Ответственный | Проверяет сценарии и ошибки | Контролирует операции и восстановление |
Секретный ключ хранится на сервере или в защищённых настройках интеграции. Его нельзя помещать в публичный код страницы, пересылать покупателю или оставлять в открытом журнале. Перед передачей диагностики поддержке удаляйте секреты и лишние данные клиента, сохраняя номера операций, время и описание ошибки.
Для API настройте поддерживаемые уведомления об изменении состояния платежа и проверку фактического состояния операции. Возврат покупателя на страницу «Спасибо» сам по себе не является подтверждением оплаты: вкладку можно закрыть, а переход может прийти раньше окончательного результата.
Повторное уведомление должно обновлять тот же заказ, а не создавать вторую отгрузку. Связь храните по номеру заказа и идентификатору платежа. Если готовая платформа скрывает журнал обмена, запросите у её поддержки способ подтвердить эту связь и результат обработки.
Как выбрать путь формирования чеков
Приём денег и формирование фискального чека — разные действия. Квитанция платёжного сервиса не заменяет кассовый документ там, где он требуется. Сначала определите обязанности именно вашего продавца по 54-ФЗ, затем выберите поддерживаемую схему.
| Ситуация | Что согласовать | Что проверить |
|---|---|---|
| Подключаете именно «Чеки от ЮKassa» для обычных платежей | Доступность услуги и ограничения, настройки, данные товаров и расчёта | Какие чеки создаёт услуга, где виден результат и кто исправляет ошибку |
| Используете стороннюю совместимую ККТ, связанную с ЮKassa | Регистрацию и договор с кассовым сервисом, поддерживаемый способ обмена | Передачу данных от оплаты к ККТ и получение результата |
| Формируете чеки самостоятельно | Собственную ККТ и интеграцию, ответственного за фискализацию | Что успешная оплата не остаётся без положенного чека |
У «Чеков от ЮKassa» есть продуктовые ограничения: сервис предназначен для обычных платежей, а не для «Безопасной сделки» и сплитования платежей. Для таких схем документация провайдера направляет к сторонней ККТ. Нельзя включать их в первую строку только потому, что деньги тоже проходят через ЮKassa. В выбранной интеграции сопоставьте разделы документации «Чеки от ЮKassa» и «Чеки через сторонние сервисы» с условиями договора.
Не включайте две независимые схемы для одного расчёта без продуманного распределения событий: можно сформировать дубли. И наоборот, отключение передачи чека в платёжном модуле допустимо только при работающем альтернативном пути. Исполнитель может оказывать техническую услугу, но распределение обязанностей определяется законом и конкретными договорами; нельзя считать, что провайдер автоматически принимает все обязанности продавца.
В номенклатуре должны совпадать названия, количества, суммы, скидки и применимые налоговые реквизиты. Предоплата, передача товара и частичный возврат могут требовать разных кассовых действий. Эти события заранее разберите с ответственным за кассу, не подставляйте универсальные значения для всех магазинов.
Учебная приёмка подключения
Возьмём вымышленный тестовый заказ: товар 1 490 ₽ и доставка 250 ₽, всего 1 740 ₽. Он создан в тестовой среде и не должен запускать настоящую отправку. Это образец задания для вашей проверки, а не подтверждение уже выполненной интеграции.
| Сценарий | Ожидаемое наблюдение |
|---|---|
| Успешная тестовая оплата | Сумма 1 740 ₽, платёж относится к одному нужному заказу |
| Покупатель закрыл страницу | Итог определяется состоянием платежа, а не фактом возврата на сайт |
| Отказ или отмена | Заказ не помечен оплаченным, покупателю понятно продолжение |
| Уведомление пришло повторно | Нет второго заказа, списания товара или задания на отгрузку |
| Ошибка чекового обмена | Проблема видна ответственному, успешная оплата не скрывает отсутствие чека |
| Проверка возврата | Сумма и чековые данные связаны с исходной операцией |
В каждом случае сохраните номер заказа, идентификатор платежа, ожидаемое и фактическое состояние, время и результат чекового обмена. Не записывайте секретный ключ. Расширенную матрицу сценариев даёт инструкция по тестированию платежей.
Тестовый магазин поддерживает не все способы оплаты. Например, обычное тестирование ЮKassa нельзя выдавать за полноценную проверку реального банковского маршрута СБП. Имитация чеков тоже не доказывает, что рабочая ККТ отправила настоящий документ в ОФД — оператору фискальных данных.
Когда переходить к рабочей оплате
Переход обоснован после договора и согласования условий, успешной приёмки магазина, готового пути фискализации и назначенного ответственного. Переключите параметры только по инструкции вашей платформы или разработчика, затем повторно сверьте рабочие идентификаторы, адрес уведомлений и доступность способов оплаты.
Если тестовая оплата проходит, а схема кассы не определена, рабочий запуск откладывается. Если уже есть подходящая собственная ККТ, альтернатива новому кассовому сервису — настроить её и проверить самостоятельное формирование чеков. Выбор зависит от поддержки интеграции и договора, а не от самого наличия аккаунта ЮKassa.
Для рабочей приёмки отдельно согласуйте допустимый порядок контрольной операции и возврата. Успешный тест без списания денег не является фактом реальной оплаты или подтверждением всех банковских и кассовых процессов. При неисправности ограничьте новый приём платежей, сохраните журнал и проверьте судьбу уже начатых операций до повторных попыток.
Лист подключения
Продавец, сайт, статус заявки и договора:
Модуль/версия или ответственный разработчик API:
Тестовый и рабочий shop ID, место хранения секрета:
Уведомления, связь заказа и платежа:
Выбранный путь ККТ, договор и ответственный:
Кто передаёт номенклатуру, скидки и чековые события:
Результаты успеха, отмены, повтора и возврата:
Что проверено в имитации, что остаётся для рабочего режима:
Условия переключения, остановки и восстановления: