Сбербанк: API для платежей и интернет‑эквайринга — полное руководство

Обзор интернет‑эквайринга Сбербанка и сценарии

Сбербанк — крупнейший эквайер в РФ. API поддерживает оплату картами (МИР/Visa/Mastercard), 3‑D Secure 2, СБП и другие опции. Подходит для интернет‑магазинов, госуслуг, подписок и услуг с холдированием средств.

Плюсы:

• Высокая надёжность и узнаваемость бренда.
• Поддержка 3‑D Secure и СБП, развитая антифрод‑инфраструктура.
• Песочница и документация с примерами типовых запросов.

Подключение: договор, доступы, окружения

Старт включает оформление договора, получение access‑данных (логин/пароль/ключи) и настройку callback‑URL. Рекомендуется разделить окружения (sandbox ↔ production) и использовать разные секреты. Убедитесь, что домены с HTTPS и корректным сертификатом.

Поток платежа: регистрация заказа, редирект, 3‑D Secure

Типовой сценарий выглядит так:

1. Регистрация заказа: отправьте запрос «register order» с суммой, валютой, описанием, orderNumber и returnUrl. В ответ получите orderId и ссылку платёжной формы банка.
2. Редирект: переведите клиента на платёжную страницу Сбербанка. Клиент вводит данные карты и проходит 3‑D Secure (если запрошено).
3. Возврат клиента: по success/fail URL, которые вы передали на первом шаге.
4. Захват/зачёт: в зависимости от модели (двухстадийная/одностадийная) средства холдируются и/или списываются.

Советы:

• Для двухстадийных сценариев храните orderId и выполняйте «complete/capture» после подтверждения от логистики/склада.
• Следите за временем жизни заказа (validity), при истечении — регистрируйте повторно.

Получение статусов и сверка

Используйте методы статусов (например, getOrderStatus) для проверки результата, а также сверяйте суммы/валюты, избегая рассинхронизации. Ведите таблицу соответствия orderNumber ↔ orderId, протоколируйте каждое изменение статуса с временной меткой.

Практики:

• Делайте периодический reconcile: сличайте ваши заказы с отчётами банка.
• Для high‑load используйте backoff и кэширование статусных ответов.

Возвраты и отмены (reverse/cancel/refund)

Поддерживаются:

• Отмена холда (reverse/cancel) до списания.
• Полный/частичный refund после списания.

Используйте идемпотентность и храните причинный код возврата. В интерфейсе для оператора делайте подсказки (частичный возврат на часть позиций, налоговые ставки, комментарии).

Вебхуки и уведомления

Подключите callback‑URL, на который Сбербанк отправит итоговый статус. Обработчик должен проверять подпись/секрет, писать идемпотентную запись результата и отвечать 2xx. При временной недоступности обеспечьте повторную обработку.

Тестирование и песочница

Проверьте:

• Успешные/неуспешные авторизации, 3‑D Secure, СБП‑сценарии.
• Сценарии reverse/refund, отмены корзины и частичные возвраты.
• Таймауты, сетевые ошибки, повторная регистрация по истечении validity.

Лучшие практики: идемпотентность, логирование, SLA

• Передавайте уникальные ключи идемпотентности в критических операциях.
• Включите корреляционные идентификаторы, чтобы связывать запросы register/ status/ refund.
• Настройте алерты по SLA: доля успешных, время подтверждения, рост отказов по do_not_honor/insufficient_funds.

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

• invalid_orderNumber: проверьте формат и уникальность.
• order_expired: повторите регистрацию с новым orderId.
• authentication_failed: проверьте ключи/подписи, среду (sandbox vs prod).
• insufficient_funds/do_not_honor: покажите пользователю нейтральное сообщение и предложите альтернативу (СБП).