Интеграция 1С с ЮKassa 2026: API v3, чеки 54-ФЗ, СБП и возвраты без боли

Клиент оплатил заказ через ЮKassa в 22:47. Утром бухгалтер открывает личный кабинет, по одному сверяет 180 платежей с 1С, вручную создаёт документы оплаты, потом отдельно проверяет, что онлайн-касса пробила чеки. На 200 платежей в день это уже час рутины и постоянный риск ошибки: один дубль оплаты, один неоформленный возврат или один чек без правильных ставок НДС — и сверка превращается в разбор между бухгалтерией, поддержкой и разработчиком.

Технический нюанс, который упускают при настройке: ЮKassa считает webhook полученным только при ответе HTTP 200. Любой другой код считается невалидным, и сервис продолжает доставку уведомления в течение 24 часов с момента события. Поэтому интеграция 1С с ЮKassa не должна жить только на входящих HTTP-уведомлениях: AI-агент Синхрон1С дополнительно делает polling GET /v3/payments каждые 15 минут и сравнивает платежи с уже загруженными документами оплаты — пропуск webhook обнаруживается до того, как клиент позвонит «деньги ушли, а заказа нет».

Ключевые факты про ЮKassa и 1С в 2026 году

• API v3 работает по HTTP Basic Auth: shopId (логин) + секретный ключ (пароль). Ключи берутся в Личном кабинете → «Интеграции» → «Ключи API»; для боевого магазина ключ выдаётся по СМС-подтверждению и скачивается ровно один раз.
• Idempotence-Key нужен для повторяемых операций: ЮKassa рекомендует UUID v4, длина ключа — не больше 64 символов. При повторе с тем же ключом и теми же параметрами API возвращает результат исходного запроса, а не создаёт второй платёж или возврат.
• Жизненный цикл платежа: pending → waiting_for_capture (для двухстадийных) → succeeded или canceled. Статусы succeeded и canceled — финальные. Точное время холда приходит в expires_at; если не сделать capture вовремя, ЮKassa отменит платёж с причиной expired_on_capture.
• 54-ФЗ: если используете «Чеки от ЮKassa», в запросе на платёж или возврат нужно передавать данные для чека: товары, контакт покупателя и параметры расчёта. Статус регистрации чека проверяется по API и в личном кабинете.
• Способы оплаты в одном API: банковские карты, SberPay, T-Pay, Mir Pay, ЮMoney, СБП (payment_method_data.type=sbp), рассрочка и «Покупки в кредит» от Сбера, B2B-сценарии по отдельным правилам.
• AI-агент Синхрон1С объединяет всё в Telegram, делает webhook + polling, контролирует чеки и шлёт уведомления о расхождениях. Настройка — 15 минут, 30 000 ₽ за проект.

В нашем опыте внедрений 80% «непонятных» проблем интеграции с ЮKassa — это три вещи: сумма позиций в receipt не бьётся с amount.value на 1 копейку из-за округления НДС, обработчик webhook в 1С не отвечает 200, и платёж висит в waiting_for_capture, потому что разработчик забыл вызвать POST /v3/payments/{id}/capture для двухстадийной схемы.

Что мы проверяем на реальном внедрении

Перед кодом мы собираем не «абстрактную интеграцию», а матрицу операций конкретной компании: полная оплата, предоплата, двухстадийная оплата, СБП, частичный возврат, отмена холда, возврат после закрытия дня, чек прихода, чек возврата, ставка НДС и источник заказа в 1С. В нашем рабочем чек-листе для ЮKassa — 27 тестовых операций: 12 оплат, 5 отмен waiting_for_capture, 6 возвратов и 4 СБП-сценария. Частая ошибка находится не в API, а в маппинге 1С: частичный возврат создаёт документ без исходного payment_id, поэтому бухгалтер видит деньги в ЮKassa, но не может связать их с заказом.

Практический вывод: не начинайте с формы оплаты. Сначала заведите в 1С отдельные реквизиты YooKassaPaymentId, YooKassaRefundId, IdempotenceKey, FiscalReceiptStatus и WebhookReceivedAt. Без этих полей поддержка быстро превращается в поиск по логам, личному кабинету и переписке с клиентом.

Личный кабинет vs API v3 vs готовый модуль ЮKassa-1С vs Синхрон1С

Типичные ошибки интеграции — и как их обойти

1. Idempotence key is too long (HTTP 400, code: invalid_request). Прилетает, когда в качестве ключа подставили длинную строку из реквизитов документа 1С. По спецификации — максимум 64 символа. Используйте UUID v4 (Новый УникальныйИдентификатор() в 1С) и сохраняйте его в реквизите документа оплаты — повторная отправка пойдёт с тем же ключом и не создаст дубль.
2. HTTP 401 Unauthorized. Самая массовая причина — в Basic Auth подставлен OAuth-токен или старый ключ из тестового магазина. Проверьте: ключ боевого магазина скачивается из ЛК один раз и активируется по СМС, тестовый ключ всегда доступен в профиле. Перепутали shopId и accountId — тоже 401.
3. Сумма позиций receipt не совпадает с amount.value. ЮKassa проверяет совпадение до копейки и отклоняет платёж. Чаще всего — округление НДС внутри vat_code: 1С считает НДС от каждой позиции и округляет вниз, а ЮKassa ждёт сумму, точно равную итогу. Решение: рассчитывать копеечную разницу и докидывать её в последнюю позицию чека.
4. Webhook не дошёл, статус в 1С не обновился. ЮKassa шлёт POST на ваш URL и ждёт именно HTTP 200; тело ответа и заголовки она игнорирует. Любой другой HTTP-код считается невалидным, после чего доставка продолжается до 24 часов с момента события. Решение: отвечать 200 OK сразу, тяжёлую обработку выносить в фоновое задание, плюс делать polling GET /v3/payments?created_at.gte=... каждые 15 минут как страховку.
5. Webhook прилетел не от ЮKassa (подмена). В обработчике обязательно фильтруйте IP источника по официальным подсетям ЮKassa: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35, 77.75.154.128/25, 2a02:5180::/32. Дополнительно запрашивайте текущий статус объекта по API — это защищает от старых или поддельных уведомлений.
6. Платёж завис в waiting_for_capture. Это нормальный статус двухстадийного платежа: средства захолдированы, нужен явный POST /v3/payments/{id}/capture. Срок списания смотрите в expires_at: если ничего не сделать до этой даты, платёж уйдёт в canceled, деньги вернутся клиенту, заказ останется без оплаты. Если двухстадийность не нужна — передавайте capture: true в запросе создания платежа.
7. Возврат отклонён или не связан с заказом. POST /v3/refunds создаётся по payment_id успешного платежа (status=succeeded) и сумме возврата. Для waiting_for_capture нужен не возврат, а cancel. Если используете чеки, проверьте, что сценарий возврата передаёт корректные позиции, НДС и контакт покупателя, иначе чек возврата не пройдет так же, как исходный чек.
8. СБП-платёж висит в pending до закрытия сеанса. При payment_method_data.type=sbp нужно передать confirmation.type=redirect, return_url и capture=true; ЮKassa вернёт confirmation_url с QR-кодом на десктопе или списком банков на мобильном. Статус останется pending, пока пользователь не подтвердит перевод в банковском приложении. Решение: отдельный сценарий обработки СБП с подсказкой клиенту и polling по payment.id.

Таблица рисков интеграции 1С и ЮKassa

Как работает AI-сверка платежей ЮKassa

После каждого платежа AI-агент:

1. Принимает webhook payment.succeeded (или payment.waiting_for_capture / refund.succeeded), проверяет IP источника и при спорном статусе запрашивает объект по API, отвечает 200 OK за миллисекунды.
2. Параллельно каждые 15 минут делает GET /v3/payments?status=succeeded&created_at.gte=... и сравнивает список с документами оплаты в 1С — ищет платежи в ЮKassa, которым нет соответствия в 1С.
3. Контролирует чеки: для каждого succeeded платежа должен быть понятный статус регистрации чека; если статус не появился в ожидаемый интервал, шлёт алёрт бухгалтеру и разработчику.
4. Отправляет сводку расхождений и зависших waiting_for_capture в Telegram — до того как клиент позвонит в поддержку.

Подключение интеграции за 3 шага

Шаг 1. Получите shopId и секретный ключ боевого магазина в ЛК ЮKassa: «Интеграции» → «Ключи API» → создать → активировать по СМС → скачать (ключ показывается ровно один раз). В разделе «HTTP-уведомления» укажите URL вашего HTTP-сервиса 1С и подпишитесь на события payment.succeeded, payment.waiting_for_capture, payment.canceled, refund.succeeded.

Шаг 2. В 1С опубликуйте HTTP-сервис (например, /hs/yookassa/notify) с методом POST: фильтр IP по подсетям ЮKassa, чтение тела, проверка event и object.id, обновление документа оплаты, ответ 200 OK. Для отправки запросов — Basic Auth shopId:secretKey, заголовок Idempotence-Key с UUID v4 на каждую операцию.

Шаг 3. Напишите @onoutnoxon — настроим коннектор за 15 минут: webhook + polling, фискализация чеков, возвраты из 1С, СБП, рассрочка и AI-сверка с уведомлениями в Telegram.

Синхрон1С — webhook + polling + AI-сверка чеков и платежей в Telegram

FAQ

Какой ключ использовать в API — секретный или OAuth-токен?

Для классической интеграции одного магазина — секретный ключ из «Интеграции» → «Ключи API», в Basic Auth: Authorization: Basic base64(shopId:secretKey). OAuth нужен только для маркетплейсов и партнёрских решений, которые работают от имени множества магазинов; в этом случае webhooks конфигурируются через POST /v3/webhooks, а не в ЛК.

Что обязательно класть в receipt для 54-ФЗ?

customer.email или customer.phone (хотя бы одно из двух), массив items с description, quantity, amount.value, vat_code, payment_subject (товар/услуга/работа) и payment_mode (полный расчёт/предоплата/аванс). В 2026 году важно не зашивать старый диапазон ставок: в справочнике ЮKassa есть коды НДС до 12, включая новые 22% и 22/122. Сумма позиций должна совпадать с amount.value платежа до копейки.

Как сделать частичный возврат?

POST /v3/refunds с payment_id исходного платежа, нужной суммой в amount и данными чека на возвращаемые позиции, если у вас подключена фискализация. Idempotence-Key — новый UUID. Возврат возможен только из статуса succeeded. Синхрон1С инициирует возврат прямо из документа в 1С.

Что делать, если webhook не дошёл?

Опираться только на webhook нельзя: обработчик может быть недоступен, а доставка уведомления ограничена 24 часами. Параллельно делайте polling GET /v3/payments?status=succeeded&created_at.gte=<последний обработанный> каждые 10–15 минут и сравнивайте с документами оплаты в 1С. Синхрон1С делает это из коробки.

Как принимать СБП через ЮKassa?

В POST /v3/payments передайте payment_method_data: { "type": "sbp" } и confirmation: { "type": "redirect", "return_url": "..." }. ЮKassa в confirmation_url отдаст QR-код (десктоп) или список банков (мобильный). После подтверждения в банковском приложении статус сменится с pending на succeeded — обрабатывайте по webhook.

Поддерживает ли ЮKassa рассрочку и кредит в API?

Да: «Покупки в кредит» от Сбера и сервис «Оплата частями». В жизненном цикле появляется «период охлаждения» — платёж остаётся в pending до suspended_until, потом автоматически уходит в succeeded или waiting_for_capture (для двухстадийных). Если клиент отказался от рассрочки — canceled.

Чем отличаются cancel и refund?

cancel доступен только для waiting_for_capture — отменяет холд, ЮKassa не берёт комиссию. refund — для succeeded, возвращает деньги клиенту, комиссия за приём не возвращается. Это частая путаница: попытка cancel на succeeded вернёт ошибку.

Можно ли использовать в агентской схеме (маркетплейс)?

Да, есть отдельные сценарии Split payments и Safe deal с распределением сумм между несколькими получателями. Чеки и возвраты в этих схемах работают по-другому — каждому получателю свой receipt. Если у вас маркетплейс, скажите об этом сразу: настройка отличается от классической.

Смотрите также

• Интеграция 1С с банком: DirectBank, txt-обмен и API без боли
• Интеграция 1С с онлайн-кассой: Атол, Эвотор
• Автоматическая выгрузка из 1С по расписанию

Стоимость интеграции — 30 000 ₽ за проект, включая публикацию HTTP-сервиса в 1С, настройку webhook + polling, фискализацию чеков 54-ФЗ, возвраты из 1С и AI-сверку. Напишите в Telegram: @onoutnoxon.

Подробнее о возможностях — на странице Синхрон1С.

Источники:

• Справочник API ЮKassa (v3): https://yookassa.ru/developers/api
• Формат взаимодействия с API, Idempotence-Key, авторизация: https://yookassa.ru/developers/using-api/interaction-format
• Жизненный цикл платежа (pending → waiting_for_capture → succeeded/canceled): https://yookassa.ru/developers/payment-acceptance/getting-started/payment-process
• Входящие уведомления (webhooks), список IP-адресов источников: https://yookassa.ru/developers/using-api/webhooks
• Возвраты через API ЮKassa: https://yookassa.ru/developers/payment-acceptance/after-the-payment/refunds
• Чеки от ЮKassa и 54-ФЗ: https://yookassa.ru/developers/payment-acceptance/receipts/54fz/yoomoney/basics
• Справочник параметров чеков и кодов НДС: https://yookassa.ru/developers/payment-acceptance/receipts/54fz/yoomoney/parameters-values
• Приём оплаты через СБП (Faster Payments System): https://yookassa.ru/developers/payment-acceptance/integration-scenarios/manual-integration/other/sbp
• Подключение СБП в 1С через ЮKassa: https://yookassa.ru/docs/support/payments/onboarding/integration/cms-module/sbp-1c
• Модуль 1С:Предприятие для ЮKassa: https://yookassa.ru/integration/1spredpriyatie-yookassa/

Для статьи использован AI-ассистент для структурирования материала и поиска источников; авторизация API v3, Idempotence-Key, статусы платежей, webhook-доставка, IP-allowlist, СБП, возвраты и параметры чеков проверены вручную по официальной документации yookassa.ru/developers и справке ЮKassa для 1С. Финальную редактуру выполнил Александр Руин, основатель habab.ru. Дата проверки: 2026-05-04.