Table of contents
- Обзор интернет‑эквайринга Сбербанка и сценарии
- Подключение: договор, доступы, окружения
- Поток платежа: регистрация заказа, редирект, 3‑D Secure
- Получение статусов и сверка
- Возвраты и отмены (reverse/cancel/refund)
- Вебхуки и уведомления
- Тестирование и песочница
- Лучшие практики: идемпотентность, логирование, SLA
- Типовые ошибки и решения
Обзор интернет‑эквайринга Сбербанка и сценарии
Сбербанк — крупнейший эквайер в РФ. API поддерживает оплату картами (МИР/Visa/Mastercard), 3‑D Secure 2, СБП и другие опции. Подходит для интернет‑магазинов, госуслуг, подписок и услуг с холдированием средств.
Плюсы:
- Высокая надёжность и узнаваемость бренда.
- Поддержка 3‑D Secure и СБП, развитая антифрод‑инфраструктура.
- Песочница и документация с примерами типовых запросов.
Подключение: договор, доступы, окружения
Старт включает оформление договора, получение access‑данных (логин/пароль/ключи) и настройку callback‑URL. Рекомендуется разделить окружения (sandbox ↔ production) и использовать разные секреты. Убедитесь, что домены с HTTPS и корректным сертификатом.
Поток платежа: регистрация заказа, редирект, 3‑D Secure
Типовой сценарий выглядит так:
- Регистрация заказа: отправьте запрос «register order» с суммой, валютой, описанием, orderNumber и returnUrl. В ответ получите orderId и ссылку платёжной формы банка.
- Редирект: переведите клиента на платёжную страницу Сбербанка. Клиент вводит данные карты и проходит 3‑D Secure (если запрошено).
- Возврат клиента: по success/fail URL, которые вы передали на первом шаге.
- Захват/зачёт: в зависимости от модели (двухстадийная/одностадийная) средства холдируются и/или списываются.
Советы:
- Для двухстадийных сценариев храните 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: покажите пользователю нейтральное сообщение и предложите альтернативу (СБП).