API Сбер эквайринга для разработчиков: v3, интеграция и вебхуки
Крайняя версия интерфейса для мерчантов и интеграторов позволяет строить надежные платежные сценарии на вебе и в мобильных приложениях. В этом гайде разберем, как устроен сбер API эквайринг в версии v3, какие эндпоинты использовать, как подключить вебхуки, отследить запрос и внедрить массовые выплаты.
![Архитектурная схема API v3 Сбер эквайринга]
Что такое API v3 Сбер эквайринга
API v3 Сбер эквайринга — это актуальная спецификация REST интерфейсов для приема платежей, возвратов, выписок и нотификаций. Она дает единый контракт для сценариев интернет-эквайринга, QR и СБП, а также дополнений вроде выплат. Версия v3 концентрируется на предсказуемых статусах, идемпотентности запросов и событиях через вебхуки, что упрощает реализацию на стороне разработчика.
Если вы ищете надежный способ подключить сбер бизнес интернет эквайринг к сайту, мобильному приложению или CRM, v3 закрывает базовые задачи: создание платежа, холд и списание, отмена, возврат, проверка статуса и асинхронные уведомления о результате.
Базовые материалы о продуктах эквайринга смотрите здесь: Интернет-эквайринг, QR и СБП эквайринг, Мобильный эквайринг, Торговый POS эквайринг.
Быстрый старт: доступы, среды, версия
Получите доступы и заключите договор
- Оформите подключение на странице Подключение и договор.
- После верификации вы получите идентификаторы мерчанта и ключи для тестовой и боевой среды.
Выберите среду
- Sandbox для разработки и автотестов.
- Production для реальных платежей.
Аутентификация и безопасность
- Типовые схемы: OAuth 2.0 по client credentials и или mTLS с клиентским сертификатом. Точный метод зависит от подключенного профиля мерчанта.
- Передача данных по TLS 1.2+.
Версионирование
- Версия фиксируется в пути эндпоинта, например v3, или заголовком Accept-Version. Соблюдайте указания в договоре и паспорте интеграции.
Формат и локаль
- JSON, кодировка UTF‑8, время в ISO 8601, валюты в ISO 4217.
![Диаграмма последовательности: мерчант, API v3, банк, вебхуки]
Основные операции: платежи, статусы, возвраты
Ниже приведена типовая карта действий и путей для api v3 сбер эквайринг. Точные адреса и поля смотрите в выданной вам документации.
| Задача |
Метод |
Путь v3 пример |
Идемпотентность |
Комментарии |
| Создать платеж |
POST |
/api/v3/payments |
Да, через заголовок Idempotence-Key |
Для оплаты картой, СБП или виджетами |
| Получить статус |
GET |
/api/v3/payments/{payment_id} |
Не применимо |
Используйте при таймаутах |
| Подтвердить холд |
POST |
/api/v3/payments/{id}/capture |
Да |
Частичное или полное списание |
| Отменить холд |
POST |
/api/v3/payments/{id}/cancel |
Да |
До списания средств |
| Возврат |
POST |
/api/v3/refunds |
Да |
Полный или частичный возврат |
| Статус возврата |
GET |
/api/v3/refunds/{refund_id} |
Не применимо |
|
| Регистрация заказа |
POST |
/api/v3/orders |
Да |
Для генерации ссылки на оплату |
| QR СБП |
POST |
/api/v3/sbp/qr |
Да |
Для выставления счета по СБП |
| Управление вебхуками |
POST GET |
/api/v3/webhooks |
Да |
Регистрация и проверка адресов |
Рекомендации по полям
- Заказывайте платеж с указанием суммы, валюты, назначения, идентификаторов order_id и customer_id.
- Храните собственный merchant_order_id для удобной сверки в отчетах.
- Передавайте заголовок Idempotence-Key с уникальным UUID на каждую операцию создания или изменения.
Вебхуки: события, подпись и повторная доставка
Вебхуки позволяют не опрашивать API, а получать подтверждение статусов событий доставки платежей и возвратов.
Типовые события
| Событие |
Когда приходит |
Что делать |
| payment.created |
Платеж создан, ожидание подтверждения |
Показать пользователю шаг аутентификации |
| payment.waiting_for_capture |
Средства заблокированы, ждут списания |
Вызвать capture при отгрузке |
| payment.succeeded |
Успешное списание |
Подтвердить заказ, выдать доступ |
| payment.canceled |
Платеж отменен |
Снять бронь товара, уведомить клиента |
| refund.succeeded |
Возврат проведен |
Обновить баланс и документооборот |
| payout.succeeded payout.failed |
Результат выплаты |
Сверка ведомостей |
| sbp.payment.succeeded |
Оплата по СБП прошла |
Отметить заказ оплаченным |
Подтверждение подлинности
- Подписывайте и проверяйте вебхуки: провайдер отправляет заголовок подписи, например X-Signature, рассчитываемый как HMAC от тела сообщения и секрета. Сверяйте timestamp и допустимое окно времени.
- Возвращайте код 2xx быстро, обработку тяжелых задач выполняйте асинхронно у себя.
- При ошибке доставки банк повторит уведомление несколько раз, поэтому используйте идемпотентную обработку по event_id.
Как отследить запрос по эквайрингу Сбера
Частый вопрос разработчиков — как отследить запрос по эквайрингу Сбера от фронта до банка. Делайте сквозную корреляцию:
Генерируйте и передавайте три идентификатора
- order_id ваш внутренний идентификатор заказа.
- заголовок Idempotence-Key для надежного повтора запроса.
- заголовок X-Request-Id для трассировки в логах.
Логируйте на каждом шаге
- Запрос к API v3, ответ, вебхук. В логах фиксируйте все три идентификатора и сумму.
Проверяйте статус через API и вебхуки
- При таймаутах не повторяйте слепо операцию создания платежа, сначала запросите статус по payment_id или по вашим метаданным.
Сверяйте результаты в Личном кабинете
Поддержка инцидентов
- В обращении в Поддержку указывайте X-Request-Id, время запроса и сумму. Это ускоряет диагностику.
Рекомендуемые заголовки
| Заголовок |
Назначение |
| Idempotence-Key |
Защита от дублей при повторах |
| X-Request-Id |
Корреляция в логах и поддержке |
| User-Agent |
Идентификация приложения версии и окружения |
| Signature |
Проверка целостности запроса, если предусмотрено |
Массовые выплаты и batch-процессы
Эквайринг массовые выплаты Сбер актуален маркетплейсам, программам лояльности и сервисам с большим количеством получателей. Типовой функционал payout API включает:
- Единовременные выплаты на карту или счет по токену получателя, а также выплаты по СБП.
- Пакетные загрузки batch через API с контролем статусов каждой строки.
- Идемпотентность на уровне батча и отдельных операций.
- Пороговые лимиты, KYC и контроль санкционных ограничений.
Рабочий процесс
- Регистрируете реестр выплат. Передаете список получателей и суммы.
- Отслеживаете статусы через вебхуки payout.succeeded и payout.failed.
- Формируете акты и сверяете комиссию в Зачислениях и отчетах.
Учтите, что выплаты доступны только после дополнительного согласования профиля мерчанта и могут иметь отдельные тарифы. Предварительно оцените экономику через Калькулятор комиссии и раздел Тарифы и комиссии 2025.
Сценарии интернет-эквайринга для Сбер Бизнес
Сценарии зависят от канала продаж и UX:
- Сайт и лендинги. Создание платежа и редирект в хостед-страницу банка или использование виджета. Подходит для быстрого запуска.
- Мобильное приложение. Интент в системный браузер или WebView, привязка токена клиента, сохранение карты по PCI DSS токенизации. Смотрите также Мобильный эквайринг.
- QR и СБП. Генерация QR счета и ожидание платежа. Гибкий вариант для офлайн точки или самовывоза — раздел QR и СБП эквайринг.
Если нужен единый стек для онлайн и офлайн, посмотрите Торговый эквайринг POS и Оборудование и кассы.
Фискализация, кассы и 54‑ФЗ
Для интернет-продаж чек должен уходить в ОФД. Доступны два подхода:
- Фискализация на стороне банка. Вы передаете состав корзины в платеж, дальше чек формируется автоматически.
- Фискализация на стороне мерчанта. Ваш софт или касса формируют чек по событиям вебхук, а затем отправляют в ОФД.
Готовые связки и драйверы смотрите в разделе Интеграции 1С и кассы. Для выбора оборудования и принтеров чеков — Оборудование и кассы.
Безопасность, идемпотентность и таймауты
- Не храните PAN и CVC у себя. Используйте токенизацию и PCI DSS совместимые решения.
- Храните секреты в защищенном хранилище, регулярно ротируйте ключи и токены.
- Используйте идемпотентность: каждый POST, изменяющий состояние, сопровождайте уникальным Idempotence-Key.
- Обрабатывайте таймауты через стратегию проверок статуса, а не через слепое повторное создание платежа.
- Следите за rate limit и реализуйте экспоненциальный backoff.
- Для повышенной защиты применяют mTLS и привязку исходящих IP адресов.
Отчеты, зачисления и комиссии
Типовые ошибки и отладка
- 400 Неверные параметры. Проверьте тело запроса, типы полей, сумму и валюту.
- 401 403 Проблемы авторизации. Перепроверьте токен или сертификат, срок действия и скоупы.
- 409 Конфликт идемпотентности. Повторяете запрос с тем же Idempotence-Key, проверьте статус операции.
- 422 Бизнес-валидация. Например, сумма вне лимитов или товар запрещен к продаже.
- 429 Превышение лимитов. Реализуйте очереди, ретраи с backoff.
- 5xx Временная ошибка. Логируйте X-Request-Id и делайте безопасный повтор.
Если кажется, что сервис недоступен, проверьте собственную сеть, обратите внимание на раздел Сбой или не работает, а затем напишите в Поддержку с полными деталями. Следите за анонсами и изменениями API в разделе Новости и лидерство. Акции на эквайринг публикуем здесь — Акции и промокоды. Отзывы интеграторов собраны в разделе Отзывы.
Полезные советы внедрения
- Первым делом реализуйте вебхуки и надежное хранилище событий, затем добавляйте оплату на фронте.
- Не смешивайте тестовые и боевые ключи. Очевидно, но это частый источник ошибок.
- Для SBP сохраняйте идентификаторы счета и QR, т.к. оплата может прийти с задержкой.
- Для массовых выплат разделяйте батчи по типам получателей и назначению платежа, это облегчает сверку и комплаенс.
Итоги и следующий шаг
API v3 открывает быстрый и безопасный путь к приему платежей, вебхукам и выплатам. Выберите подходящий сценарий, подключите вебхуки и идемпотентность, настройте сверку и отчеты — и вы готовы к масштабированию.
Готовы начать интеграцию сбер api эквайринг