Инструкция по подключению сервиса "Безопасные сделки" на тестовом стенде
📋 Оглавление
- Пререквизиты
- Этап 1: Работа со Сбер API
- Этап 2: Работа с номинальным счетом и УКЭП
- Этап 3: Регистрация и тестирование
- Важные особенности работы с сервисом
Пререквизиты
Перед началом работы убедитесь, что выполнены следующие условия:
-
Открыт расчетный счет в Сбере и заключен договор ДБО «СберБизнес»
- Как сделать: обратитесь в любое отделение Сбера. Список офисов
-
Изучена договорная документация по сервису
- Где найти: на сайте Банка
Этап 1: Работа со Сбер API
Шаг 1.1: Подключение к каналу Сбер API
Пройдите все шаги по подключению к Сбер API по инструкции.
Результат: Подключение к Сбер API завершено, личный кабинет готов к работе.
Шаг 1.2: Получение данных тестового стенда
Направьте письмо в адрес supportdbo2@sberbank.ru для получения данных тестового стенда.
Используйте шаблон обращения:
Тема письма: Sber API | наименование вашей организации
Текст обращения:
Сервис: Безопасные сделки
Стенд: ТЕСТ | ПРОМ выберите стенд, по которому обращаетесь
ИНН: укажите ИНН вашей организации
Client_ID: уникальный идентификатор сервиса
Суть обращения: потребность, описани е ошибки, программный запрос в текстовом виде, ответ на запрос, лог
Шаг 1.3: Настройка TLS-сертификатов
Установите и проверьте сертификаты по инструкции.
Результат: TLS-сертификаты для тестового стенда установлены и проверены.
Шаг 1.4: Получение в тестовом личном кабинете СберБизнес токенов доступа
Получите в тестовом личном кабинете СберБизнес access token и refresh token по инструкции (раздел "Получить/обновить/удалить пару access_token и refresh_token").
🔍 Важно
Если во вкладке Ключи доступа отсутствует кнопка Создать ключ, необходимо обратиться в поддержку: supportdbo2@sberbank.ru.
Результат: Получены токены доступа для тестового стенда (для разового использования).
Шаг 1.5: Реализация автоматического обновления токенов доступа на тестовом стенде
Реализуйте автоматическое обновление access token и refresh token на тестовом стенде по инструкции.
Результат: Реализовано автоматическое обновление токенов доступа на тестовом стенде (для постоянного использования).
Этап 2: Работа с тестовым сертификатом
Шаг 2.1: Получение тестового сертификата для работы с тестовым стендом
⚠️ Важное условие: для отправки любого POST-запроса в API «Безопасные сделки» требуется корректная электронная подпись, сформированная согласно Правилам наложения подписи. Запросы без валидной ЭП обрабатываться не будут.
На тестовом стенде необходимо использовать тестовый ГОСТ сертификат (34.10-2012 256 бит), выпущенный с помощью любого тестового удостоверяющего центра.
⚠️ Обратите внимание: выпуск сертификата не входит в зону ответственности сервиса «Безопасные сделки». Все вопросы по получению, продлению или настройке сертификата решаются напрямую с вашим удостоверяющим центром.
Результат: Получен тестовый сертификат для подписания запросов на тестовом стенде.
Этап 3: Регистрация и тестирование
Шаг 3.1: Проверка подписи на тестовом стенде
Передайте в адрес поддержки продукта (prom_teh_safe_pay@sberbank.ru) строку подписи над произвольным контентом, и этот контент.
С правилами наложения подписи можно ознакомиться на странице
Результат: Площадка получит информацию о корректности формирования подписи.
Шаг 3.2: Регистрация площадки на тестовом стенде
Зарегистрируйте площадку на тестовом стенде с помощью вызова метода POST/v1/nominal-account/signup (для схемы Бенефициар-заказчик) или POST/v1/secure-deals/signup (для схемы Бенефициар-исполнитель).
ℹ️ Примечание
При вызове метода необходимо сгенерировать номер тестового номинального счета (маска счета аналогична расчетному счету).
Не забудьте подписать запрос в соответствии с правилами наложения подписи.
Результат: Площадка зарегистрирована на тестовом стенде и может начать процесс тестирования. Клиенту в ответ придет параметр nominalAccountId, который необходимо сохранить для дальнейшего использования.
Шаг 3.3: Проце сс тестирования
Чек-лист прохождения этапа тестирования с сервисом Безопасные сделки
| № | Что необходимо сделать | Как это сделать | Результат |
|---|---|---|---|
| 1 | Добавить бенефициара(-ов) в реестр | С помощью вызова метода POST/v1/nominal-account/beneficiaries/create (для схемы Бенефициар-заказчик) или POST/v1/secure-deals/beneficiaries (для схемы Бенефициар-исполнитель) | Бенефициар(-ы) добавлен в реестр В ответ на запрос придет параметр beneficiaryId, который необходимо сохранить для дальнейшего использования |
| 2 | Ознакомиться с правилами обновления данных и удаления бенефициара | Удаление бенефициара и изменение его данных выполняются только посредством вызова со стороны клиента соответствующих методов POST/beneficiaries/delete и POST/beneficiaries/update (для схемы Бенефициар-заказчик) или POST/beneficiaries/delete и POST/beneficiaries/update (для схемы Бенефициар-исполнитель). Операции удаления бенефициара и изменения его данных не доступны через обращение в поддержку продукта и выполняются только программно через вызовы API | Клиент ознакомился с правилами обновления данных и удаления бенефициара |
| 3 | Ознакомиться с особенностями работы с возвратами на номинальном счете | Ознакомиться с особенностями работы с возвратами можно, изучив соответствующий пункт в разделе Важные особенности работы с сервисом на данной странице | Клиент ознакомился с особенностями работы с возвратами на номинальном счете |
| 4 | Ознакомиться с рекомендациями по использованию API | Ознакомиться с рекомендациями по использованию API можно по ссылке в соответствующем разделе | Клиент ознакомился с рекомендациями по использованию API |
| 5 | Ознакомиться с особенностями работы с тестовым стендом | Ознакомиться с особенностями работы с тестовым стен дом можно, изучив соответствующий пункт в разделе Важные особенности работы с сервисом на данной странице | Клиент ознакомился с особенностями работы с тестовым стендом |
| 6 | Ознакомиться с рекомендациями по формированию назначения платежа при пополнении номинального счета на промышленном стенде | Ознакомиться с рекомендациями по формированию назначения платежа при пополнении номинального счета можно, изучив соответствующий пункт в разделе Важные особенности работы с сервисом на данной странице | Клиент ознакомился с рекомендациями по формированию назначения платежа при пополнении номинального счета на промышленном стенде |
| 7 | Провести тестирование | Реализовать и проверить сценарии работы вашей площадки с сервисом Безопасные сделки | Этап тестирования с сервисом Безопасные сделки завершен |
| 8 | Провести демо реализации | Напишите письмо в адрес поддержки продукта (prom_teh_safe_pay@sberbank.ru) для демонстрации демо реализации (в рамках взаимодействия с сервисом Безопасные сделки) в online формате | Клиент провел демо реализации совместно с командой продукта |
Важные особенности работы с сервисом
Возможна ситуация, когда при выводе средств с номинального счета в другие банки по реквизитам деньги списались, но не были зачислены получателю.
Это происходит, если банк получателя отклонил платеж. Например, из-за некорректных реквизитов.
В рамках сервиса это работает так:
- Площадка исполняет сделку.
- Банк списывает деньги с номинального счета.
- Сделка и транзакция переходят в успешный статус.
- Платеж уходит в банк получателя.
- Банк получателя отклоняет платеж (например, из-за ошибки в реквизитах получателя).
- В этом случае в течение 5 рабочих дней будет осуществлен возврат на номинальный счет (данный возврат будет отображаться на номинальном счете, как транзакция кредита в пользу бенефициара).
Узнать о возникновении таких транзакций возврата можно при помощи вызова метода GET/transactions/refunds.
Важно: возврат не меняет статус исходной сделки и исходной транзакции. Для сервиса сделка и транзакция уже исполнены, потому что деньги были успешно списаны с номинального счета.
После получения возврата необходимо повторно создать и исполнить сделку с корректными реквизитами получателя (для схемы Бенефициар-заказчик) или повторно создать платеж для вывода средств с корректными реквизитами получателя (для схемы Бенефициар-исполнитель).
Для внутренних переводов Сбер-Сбер логика другая: если возникает ошибка, деньги не списываются с номинального счета, а транзакция сразу переходит в ошибку.
На тестовом стенде эмулируются различные сценарии обработки запросов. Конфигурация включает вероятность возникновения следующих событий:
- Возврат платежа при выводе средств по реквизитам счета.
- Отказ платежа при переводе между бенефициарами в рамках одного номинального счета.
- Отказ платежа при выводе средств по Системе быстрых платежей (СБП) в направлении В2С.
- Гарантированный отказ платежа при выводе средств по СБП В2С, если номер телефона получателя (payee.phone) в запросе содержит "5".
- Отказ в создании чека для самозанятого.
- Отказ в проверке самозанятого при исполнения сделки.
- Гарантированный отказ в создании чека для самозанятого, если БИК банка получателя (selfEmployedData.bankBIC) в запросе равен "044525593".
Иные особенности при работе с тестовым стендом:
- При запросе информации по чеку после успешной инициации его создания, в ответе всегда возвращается константная ссылка на чек (receiptLink = https://lknpd.nalog.ru/api/v1/receipt/333304070236/2018xravsx/print ).
- При создании чека для самозанятого отсутствует проверка ИНН (selfEmployedData.inn) в запросе (в отличии от промышленного стенда).
- При создании бенефициара на тестовом стенде его баланс будет пополнен на 1000000 рублей.
- Если в 08:00 по МСК баланс бенефициара будет менее 100 рублей, он автоматически пополнится на 1000000 рублей.
С целью корректного распределения платежей в реестре бенефициаров рекомендуем при формировании документа на пополнения номинального счета указывать в назначении платежа:
- для Бенефициаров — корпоративных клиентов (ЮЛ, ИП)
- ИНН Бенефициара и реквизиты Договора –основания (договор между бенефициаром и владельцем номинального счета).
Пример: «Пополнение ном. счета по бенефициару ИНН 7788995544, по договору от 15.04.2024 № 385-58, без НДС».
- для Бенефициаров — физических лиц
- ФИО в именительном падеже (полностью) и реквизиты Договора–основания (договор между бенефициаром и владельцем номинального счета).
Пример: «Пополнение ном. счета по бенефициару Иванов Иван Иванович, по договору от 15.04.2024 № 385-78, без НДС».