ym88659208ym87991671
Сервис «Корпоративные подписки» | Документация для разработчиков

Сервис «Корпоративные подписки»

Обновлено 12 апреля 2024

Информация о сервисе

Корпоративные подписки – это сервис для организации расчетов с юридическими лицами (ЮЛ) и индивидуальными предпринимателями (ИП), который позволяет получать сведения о подписчиках и безакцептно списывать денежные средства за предоставление услуг или товаров.

Ядро механизма сервиса составляют платежные требования, которые используются в качестве платежных документов для расчетов между компаниями.

Платежное требование

Платежное требование - это документ, используемый для безналичных расчетов между юридическими лицами, в котором поставщик предъявляет должнику претензию за неуплату задолженности по договору. Банк на основании этого документа списывает сумму задолженности со счета плательщика в пользу получателя.

Основное различие между платежным требованием и платежным поручением заключается в инициаторе платежа. В платежном поручении инициатором является владелец счета, тогда как в платежном требовании - получатель денег (кредитор, поставщик, продавец или исполнитель услуг). Кредитор оформляет платежное требование и направляет его в банк для исполнения. Часто для выполнения платежного требования требуется акцепт (согласие) плательщика.

Платежные требования могут быть с предварительным акцептом или без него. Акцепт - это согласие должника оплатить задолженность в определенный срок. Если акцепт не предусмотрен договором, то срок составляет 5 рабочих дней. Без акцепта банк имеет право списать деньги с расчетного счета клиента в определенных случаях, например, по решению суда на основании исполнительных документов.

Другая часть механизма построена на предварительном акцепте (у себя мы его называем Заранее данный акцепт - ЗДА) на списание денежных средств со счета подписчика.

До начала разработки интеграции с сервисом потребуется:

  • Заключить договор с Банком на использование сервиса "Корпоративные подписки".
  • Завершить интеграцию со СберБизнес ID.
    Без сервиса СберБизнес ID настроить работу "Корпоративные подписки" невозможно.
  • Направить ссылку на вашу оферту в Банк на почту supportdbo2@sberbank.ru. Оферта должна включать условия предоставления услуг или продажи товаров по подписке.

Терминология

  • Заявление на подключение подписки (далее по тексту - Подписка) – документ, который включает в себя Согласие, акцепт Оферты и Заранее данный акцепт.
    • Согласие – документ, в котором Клиент дает согласие на обработку, получение и передачу сведений о компании Клиента через канал Sber API.
    • Оферта – условия вашего сервиса, на которых вы будете предоставлять услуги или поставлять товары Клиентам. В рамках Заявления на подключение подписки содержится акцепт Оферты.
    • Заранее данный акцепт (далее по тексту - ЗДА) – временное согласие Клиента на списание денежных средств в счет оплаты предоставленных услуг или товаров по подписке. Наличие Заранее данного акцепта позволяет по запросу от вашей компании Банку списывать средства со счета Клиента без дополнительного согласования.
  • Оформить Подписку – подписать Заявление на подключение подписки.
  • Digest платежного требования – набор значимых полей документа, который подписывается электронной подписью (ЭП).

Схема работы сервиса

Схема работы сервиса

Варианты реализации

В рамках Платформы вы самостоятельно разрабатываете ролевую модель и настраиваете права доступа к функциональности.

Ниже, в качестве примера, приведена диаграмма вариантов использования:

Варианты реализации
  1. Предложите Клиенту оформить Подписку
Оформить подписку

Для наличия возможности безакцептного списания денежных средств со счета Клиента потребуется получить от него согласие на такие списания. Такое согласие можно получить при оформлении Подписки Клиентом.

Клиент становится подписчиком после подписания Заявления на подключение подписки (далее по тексту - оформить Подписку). Для оформления Подписки используется сервис "СберБизнес ID": на Платформе необходимо организовать клиентский путь через СберБизнес ID.

Есть 2 варианта организации клиентского пути:

СценарийКлиент авторизуется с помощью СберБизнес ID, через некоторое время выбирает тариф и оформляет Подписку
ОсобенностиКлиент авторизуется с помощью СберБизнес ID - Платформа получает всю информацию о Клиенте, при этом он еще НЕ подписчик.
Спустя некоторое время Клиент выбирает тариф подписки - оформляет Подписку, Платформа получает информацию о счете и разрешение на безакцептное списание.
Когда актуально- У вас есть бесплатный пробный период
- Предусмотрена бесплатная функциональность для авторизованных пользователей Платформы
Что следует учестьДоступы параметра scope в рамках сервиса "Корпоративные подписки" работают на расширение.
Платформа должна "узнавать" клиентов-подписчиков при повторном посещении. Если такой механизм не предусмотрен, то Клиенту-подписчику потребуется повторно пройти авторизацию и оформить Подписку.
Вариант 1

Используемые ресурсы

№МетодТочка вызоваОписаниеОперация в scope
1Alt text/v2/oauth/authorizeПолучение кода авторизацииopenid
2Alt text/v2/oauth/tokenПолучение токена доступаopenid
3Alt text/v2/oauth/user-infoПолучение информацииopenid
  1. Спишите оплату с Клиента за использование вашего сервиса
Списание платы за подписку

Шаги

  1. Получить access_token
  2. Проверить подписку Клиента
  3. Создать платежное требование
  4. Получить статус платежного требования

Участники usecase

  • Платформа - любой web-ресурс (сайт, интернет-магазин, мобильное приложение и т.д.), который Вы используете рамках клиентского пути Клиентов;
  • Банк - в контексте данного usecase представляет из себя ресурсы и ресурсы Sber API, к которым обращается Платформа.

Предусловия

  • Отсутствуют

Постусловия

  • Платформа получила подтверждение исполнения платежного требования
Вариант 1

Используемые ресурсы

№МетодТочка вызоваОписаниеОперация в scopeШаг в схеме
1Alt text/v2/oauth/authorizeПолучение кода авторизацииopenid1. Получить access_token
2Alt text/v2/oauth/tokenПолучение токена доступаopenid1. Получить access_token
3Alt text/v2/oauth/user-infoПолучение информацииopenid1. Получить access_token
4Alt text/v1/partner-info/advance-acceptancesПолучить сведения о подписчикахGET_ADVANCE_ACCEPTANCES2. Проверить подписку Клиента
5Alt text/v1/payment-requests/outgoingОтправить запрос на безакцептное списаниеPAYMENT_REQUEST_OUT3. Создать платежное требование
6Alt text/v1/payment-requests/outgoing/{externalId}/stateПолучить статус запросаPAYMENT_REQUEST_OUT4. Получить статус платежного требования

Получить сведения о подписчиках (/v1/partner-info/advance-acceptances)

Alt text https://fintech.sberbank.ru:9443/fintech/api/v1/partner-info/advance-acceptances

Ресурс /v1/partner-info/advance-acceptances позволяет получить сведения о клиентах, которые подключились или отписались. В ответе возвращается массив данных с перечнем подписчиков и отписавшихся на запрашиваемый день. Для поддержания актуальной информации необходимо осуществлять ежедневный запрос информации. В массиве данных по клиентам также содержится информация с реквизитным составом, которую дальше можно использовать в запросах на безакцепное списание.

Для получения сведений необходимо отправить GET-запрос /v1/partner-info/advance-acceptances с токеном доступа (access_token) пользователя собственной организации в параметре Authorization заголовка, а также датой, на которую запрашиваете информацию, и идентификатор сервиса (clientId) в querry-параметрах запроса.

В параметре scope ссылки авторизации пользователя вашей компании должен быть указан сервис GET_ADVANCE_ACCEPTANCES для получения доступа к этому ресурсу.


Для обращения к ресурсу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/fintech/api
  • Промышленный контур https://fintech.sberbank.ru:9443/fintech/api

Request

/v1/partner-info/advance-acceptances
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^([a-zA-Z0-9]){38}$requiredAccess token пользователя, полученный через SSO.
QUERRY PARAMETERS
datedata-timeISO 8601 YYYY-MM-DD^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$requiredДата (подключения или отключения),
clientIdstringstring\d{1,10}requiredИдентификатор платформы

Responses

200 (OK)
НаименованиеТипОбязательностьОписание
AdvanceAcceptance [
{
AdvanceAcceptance 1 {
activebooleanoptionalПризнак активности ЗДА. Значение "true" возвращается по клиентам, подписавшим ЗДА.
Если Клиент не подписал ЗДА или отменил его у себя в СберБизнес, то будет возвращаться значение "false",
bundlesArray[AdvanceAcceptanceBundle]optionalИнформация о пакете услуг,
payerAccountstringoptionalСчет плательщика,
payerBankBicstringoptionalБИК банка плательщика,
payerBankCorrAccountstringoptionalКорсчет банка плательщика,
payerInnstringoptionalИНН плательщика,
payerNamestringoptionalНаименование плательщика,
payerOrgIdHashstringoptionalИдентификатор организации плательщика,
purposestringoptionalНазначение платежа,
sinceDatestringoptionalДата начала действия ЗДА,
untilDatestringoptionalДата окончания действия ЗДА
}
AdvanceAcceptanceBundle {
codestringoptionalКод пакета услуг,
namestringoptionalНаименование пакета услуг,
sinceDatestringoptionalДата подключения пакета услуг,
untilDatestringoptionalДата отключения пакета услуг,
currentStatestringoptionalСтатус пакета услуг в настоящее время.
Возможные варианты: ACTIVE, NOT_PAID, DEACTIVATED
}
]
400 (Bad request)
CauseMessageDescription
DESERIALIZATION_FAULTНеверный формат запросаДанные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULTОшибка валидацииДанные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
НаименованиеТипОбязательностьОписание
ResourceFault {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
checksArray[Check]optionalСписок проверок, приведших к ошибке,
fieldNamesArray[string]optionalНазвания полей с некорректным значением (только для VALIDATION_FAULT)
}
Check [
{
levelstringoptionalУровень результата = ['ERROR', 'WARNING'],
messagestringoptionalСообщение,
fieldsArray[string]optionalНазвания полей (при наличии связи с моделью)
}
]
401 (Unauthorized Error)
CauseMessageDescription
UNAUTHORIZEDaccessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
403 (Forbidden)
CauseMessageDescription
ACTION_ACCESS_EXCEPTIONОперация не может быть выполнена: доступ к ресурсу запрещенИспользуемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция GET_ADVANCE_ACCEPTANCES. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.
Вы использовали access_token пользователя Клиента, а не пользователя вашей организации. Нужно использовать access_token пользователя вашей организации.
Проверьте используемый access_token в header и clientId в querry-параметре запроса. Оба параметра должны принадлежать одной вашей организации.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
404 (Not found)
CauseMessageDescription
DATA_NOT_FOUND_EXCEPTIONНе найдено ни одного заранее данного акцепта за указанную датуНа указанную в запросе дату никто не подписался и не отписался
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
500 (Internal Server Error)
CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
503 (Service Temporarily Unavailable)
CauseMessageDescription
UNAVAILABLE_RESOURCE_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

Отправить запрос на безакцептное списание (/v1/payment-requests/outgoing)

ВАЖНО!

Выставить платежное требование Клиенту можно не раньше даты, следующей за датой оформления Подписки.

Например, Клиент оформил Подписку 15 января. На следующий день, 16 января, можно будет сформировать платежное требование для списания денежных средств. Если сформировать платежное требование в день оформления Подписки, то платежное требование не будет исполнено - оно встанет в "Картотеку" в СберБизнес Клиента на ручное подтверждение.

Alt text https://fintech.sberbank.ru:9443/fintech/api/v1/payment-requests/outgoing

Ресурс /v1/payment-requests/outgoing позволяет создавать платежные требования, где получателем средств является ваша компания.

Для создания платежного требования необходимо отправить POST-запрос /v1/payment-requests/outgoing с токеном доступа (access_token) пользователя собственной организации в параметре Authorization заголовка и реквизитами платежного требования в теле запросе.

В параметре scope ссылки авторизации пользователя должен быть указан сервис PAYMENT_REQUEST_OUT для получения доступа к этому ресурсу.


Для обращения к ресурсу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/fintech/api
  • Промышленный контур https://fintech.sberbank.ru:9443/fintech/api

Request

/v1/payment-requests/outgoing
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^([a-zA-Z0-9]){38}$requiredAccess token пользователя, полученный через SSO.
BODY
PaymentRequestOut {
acceptanceTermstringstring^[1-5]{1}$optionalСрок для акцепта (поле 36). Указывается количество дней для получения акцепта плательщика,
amountnumberfloat^[0-9]+(.[0-9]+)?$requiredСумма платежа,
datestringISO 8601 YYYY-MM-DD^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$requiredДата составления документа,
deliveryKindstringstring^(электронно|срочно|0)$optionalВид платежа: электронно, срочно
Если не заполнено или 0, то будет присвоено значение "электронно",
digestSignaturesArray[Signature]objectoptionalЭлектронные подписи по дайджесту документа,
externalIdstringUUID^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$requiredИдентификатор документа, присвоенный партнером,
numberstringstring^[0-9]$optionalНомер документа,
operationCodestringstring^02$requiredКод операции,
payeeAccountstringstring^[0-9]$requiredСчет получателя платежа,
payeeBankBicstringstring^[0-9]{9}$requiredБИК получателя платежа,
payeeBankCorrAccountstringstring^[0-9]{20}$requiredКорсчет банка получателя платежа,
payeeInnstringstring^([0-9]{5}|[0-9]{10}|[0-9]{12}|0)$optionalИНН получателя платежа,
payeeNamestringstring^[0-9a-zA-Zа-яА-ЯеЁ \t]+$requiredПолное наименование получателя платежа,
payerAccountstringstring^[0-9]{20}$requiredСчет плательщика,
payerBankBicstringstring^[0-9]{9}$requiredБИК банка плательщика,
payerBankCorrAccountstringstring^[0-9]{20}$requiredКорсчет банка плательщика,
payerInnstringstring^([0-9]{5}|[0-9]{10}|[0-9]{12}|0)$requiredИНН плательщика,
payerNamestringstring^[0-9a-zA-Zа-яА-ЯеЁ \t]+$requiredПолное наименование плательщика,
paymentConditionstringstring^(1|2)$requiredУсловие оплаты (поле 35).

Указывается цифра "1" - заранее данный акцепт плательщика или цифра "2" - требуется получение акцепта плательщика,
prioritystringstring^[1-5]{1}$requiredОчередность платежа,
purposestringstring^[a-zA-Z0-9._ -]{1,210}$requiredНазначение платежа.
Заполнять значением purpose, полученным в ответе на запрос GET /v1/partner-info/advance-acceptances

Если необходимо дополнить назначение, поставьте точку и укажите свою информацию,
vatArray[Vat]objectrequiredДанные НДС,
voCodestringstring^[0-9]{5}$requiredКод вида валютной операции
}
Signature [
{
base64Encodedstringbase64^[a-zA-Z0-9]+$optionalЗначение электронной подписи (ЭП), закодированное в Base64.
Можно передать одну или две ЭП вместе с реквизитами создаваемого документа - ссылка на ЭП.
Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес,
certificateUuidstringUUID^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$optionalУникальный идентификатор сертификата ключа проверки электронной подписи
}
]
Vat {
amountnumberfloat^[0-9]+(.[0-9]+)?$optionalСумма НДС,
ratestringstring^[0-9]{0,2}$optionalСтавка НДС,
typestringstring^(INCLUDED|NO_VAT|MANUAL)$requiredСпособ расчета НДС.

INCLUDED - НДС включен в сумму платежа
NO_VAT - не облагается НДС
MANUAL - ручной ввод НДС
}

digestSignatures

Передача электронной подписи

Передача электронной подписи (ЭП) осуществляется с использованием массива digestSignatures, где каждый элемент представляет собой подпись (Signature). Каждая подпись должна содержать следующие обязательные поля:

Наименование поляОписание поляПример
base64Encoded (string)Значение ЭП документаHlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==
certificateUuid (string)Идентификатор сертификата, использованного при создании ЭП (можно узнать, обратившись к ресурсу /v1/crypto или /v1/crypto/eio)22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

В документе можно передать одну или две электронных подписи вместе с реквизитами создаваемого документа. Если подписи переданы через API, то они сохраняются вместе с документом, а сам документ продолжает свой жизненный цикл. Если подписи не были переданы, то документ сохраняется в начальном статусе и ожидает дальнейшей подписи в интерфейсе СберБизнес.

Документ может быть подписан следующими наборами подписей:

  • одна (единственная) подпись;
  • первая и вторая подписи.

При этом нельзя сочетать подпись, имеющую единственное полномочие, с подписью, имеющей первую или вторую подписи.

Порядок наложения подписи не имеет значения при наложении первой и второй подписей. Состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля при создании пользователя в СберБизнес.

Формат дайджеста
Наименование поляОписание поляПример
acceptanceTermСрок акцепта5
amountСумма платежа100.01
dateДата составления документа31.12.2018
externalIdИдентификатор документа, присвоенный сервисом22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
operationCodeКод операции02
payeeAccountНомер счета получателя40802810600000200000
payeeBankBicБИК получателя044525225
payeeBankCorrAccountКорсчет банка получателя30101810400000000225
payeeInnИНН получателя0452566242
payeeNameПолное наименование получателя платежаОбщество с ограниченной ответственностью "Получатель"
payerAccountСчет плательщика40802810600000200000
payerBankBicБИК плательщика044525225
payerBankCorrAccountКорсчет банка плательщика30101810400000000225
payerInnИНН плательщика8554122325
payerNameПолное наименование плательщикаОбщество с ограниченной ответственностью "Клиент"
paymentConditionУсловие оплаты (1/2)1
priorityОчередность платежа5
purposeНазначение платежаОплата товара по договору №123 от 01.08.2018. НДС не облагается

Responses

201 (Created)
НаименованиеТипОбязательностьОписание
PaymentRequestOut {
acceptanceTermstringoptionalСрок для акцепта (поле 36). Указывается количество дней для получения акцепта плательщика,
amountnumberrequiredСумма платежа,
bankCommentstringoptionalБанковский комментарий к статусу документа,
bankStatusstringoptionalСтатус документа,
crucialFieldsHashstringoptionalHash от ключевых полей документа,
datestringrequiredДата составления документа,
deliveryKindstringoptionalВид платежа: электронно, срочно
Если не заполнено или 0, то будет присвоено значение "электронно",
digestSignaturesArray[Signature]optionalЭлектронные подписи по дайджесту документа,
externalIdstringrequiredИдентификатор документа, присвоенный партнером,
numberstringoptionalНомер документа,
operationCodestringrequiredКод операции,
payeeAccountstringrequiredСчет получателя платежа,
payeeBankBicstringrequiredБИК получателя платежа,
payeeBankCorrAccountstringrequiredКорсчет банка получателя платежа,
payeeInnstringoptionalИНН получателя платежа,
payeeNamestringrequiredПолное наименование получателя платежа,
payerAccountstringrequiredСчет плательщика,
payerBankBicstringrequiredБИК банка плательщика,
payerBankCorrAccountstringrequiredКорсчет банка плательщика,
payerInnstringrequiredИНН плательщика,
payerNamestringrequiredПолное наименование плательщика,
paymentConditionstringrequiredУсловие оплаты (поле 35).

Указывается цифра "1" - заранее данный акцепт плательщика или цифра "2" - требуется получение акцепта плательщика,
prioritystringrequiredОчередность платежа,
purposestringrequiredНазначение платежа.
Заполнять значением purpose, полученным в ответе на запрос GET /v1/partner-info/advance-acceptances

Если необходимо дополнить назначение, поставьте точку и укажите свою информацию,
vatArray[Vat]requiredДанные НДС,
voCodestringrequiredКод вида валютной операции
}
Signature [
{
base64EncodedstringoptionalЗначение электронной подписи (ЭП), закодированное в Base64.
Можно передать одну или две ЭП вместе с реквизитами создаваемого документа - ссылка на ЭП.
Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес,
certificateUuidstringoptionalУникальный идентификатор сертификата ключа проверки электронной подписи
}
]
Vat {
amountnumberoptionalСумма НДС,
ratestringoptionalСтавка НДС,
typestringrequiredСпособ расчета НДС.

INCLUDED - НДС включен в сумму платежа
NO_VAT - не облагается НДС
MANUAL - ручной ввод НДС
}
202 (Accepted)
CauseMessageDescription
WORKFLOW_FAULTДокумент сохранен, но обработка ЭП или принятие документа завершились ошибкой. ЭП не может быть принятаНеизвестный идентификатор сертификата. Проверьте корректность отправленной ЭП в запросе.
Возможно, была отправлена ЭП с типом "Первая подпись" или "Вторая подпись". Для случаев, когда используется ЭП подписантов с типом "Первая подпись" или "Вторая подпись" для принятия документа в обработку требуется передать в запросе данные обеих подписей.
НаименованиеТипОбязательностьОписание
ResourceFault {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
checksArray[Check]optionalСписок проверок, приведших к ошибке,
fieldNamesArray[string]optionalНазвания полей с некорректным значением (только для VALIDATION_FAULT)
}
Check [
{
levelstringoptionalУровень результата = ['ERROR', 'WARNING'],
messagestringoptionalСообщение,
fieldsArray[string]optionalНазвания полей (при наличии связи с моделью)
}
]
400 (Bad request)
CauseMessageDescription
DESERIALIZATION_FAULTНеверный формат запросаДанные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
WORKFLOW_FAULTНевозможно идентифицировать организацию плательщикаПроверьте корректность указанных реквизитов плательщика.
Невозможно идентифицировать банк получателя по указанным номеру БИК и корреспондентскому счетуПроверьте корректность указанных реквизитов получателя платежа - атрибуты payeeBankBic и payeeBankCorrAccount
Документ с таким externalId уже существует в системеИспользуется externalId, который уже есть в системе (дубль). Сгенерируйте новый externalId и повторите запрос.
VALIDATION_FAULTОшибка валидацииДанные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
НаименованиеТипОбязательностьОписание
ResourceFault {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
checksArray[Check]optionalСписок проверок, приведших к ошибке,
fieldNamesArray[string]optionalНазвания полей с некорректным значением (только для VALIDATION_FAULT)
}
Check [
{
levelstringoptionalУровень результата = ['ERROR', 'WARNING'],
messagestringoptionalСообщение,
fieldsArray[string]optionalНазвания полей (при наличии связи с моделью)
}
]
401 (Unauthorized Error)
CauseMessageDescription
UNAUTHORIZEDaccessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
403 (Forbidden)
CauseMessageDescription
ACTION_ACCESS_EXCEPTIONОперация не может быть выполнена: доступ к ресурсу запрещенИспользуемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция PAYMENT_REQUEST_OUT. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.
Вы использовали access_token пользователя Клиента, а не пользователя вашей организации. Нужно использовать access_token пользователя вашей организации.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
500 (Internal Server Error)
CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
503 (Service Temporarily Unavailable)
CauseMessageDescription
UNAVAILABLE_RESOURCE_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

Получить статус запроса (/v1/payment-requests/outgoing/{externalId}/state)

Alt text https://fintech.sberbank.ru:9443/fintech/api/v1/payment-requests/outgoing/{externalId}/state

Ресурс /v1/payment-requests/outgoing/{externalId}/state позволяет получить статус ранее отправленного платежного требования.

Для получения статуса необходимо отправить GET-запрос /v1/payment-requests/outgoing/{externalId}/state с токеном доступа (access_token) пользователя собственной организации в параметре Authorization заголовка и идентификатор документа (externalId) в querry-параметре запроса.

В параметре scope ссылки авторизации пользователя вашей компании должен быть указан сервис PAYMENT_REQUEST_OUT для получения доступа к этому ресурсу. ресурсу.


Для обращения к ресурсу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/fintech/api
  • Промышленный контур https://fintech.sberbank.ru:9443/fintech/api

Request

/v1/payment-requests/outgoing/{externalId}/state
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^([a-zA-Z0-9]){38}$requiredAccess token пользователя, полученный через SSO.
PATH PARAMETERS
externalIdstringUUID^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$requiredИдентификатор документа, присвоенный вами при создании исходящего платежного требования

Responses

200 (OK)
НаименованиеТипОбязательностьОписание
PaymentDocState {
bankCommentstringoptionalБанковский комментарий к статусу документа,
bankStatusstringoptionalСтатус документа,
channelInfostringoptionalКомментарий, специфичный для документа, полученного по данному каналу,
crucialFieldsHashstringoptionalHash от ключевых полей документа
}
400 (Bad request)
CauseMessageDescription
DESERIALIZATION_FAULTНеверный формат запросаДанные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULTОшибка валидацииДанные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
НаименованиеТипОбязательностьОписание
ResourceFault {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
checksArray[Check]optionalСписок проверок, приведших к ошибке,
fieldNamesArray[string]optionalНазвания полей с некорректным значением (только для VALIDATION_FAULT)
}
Check [
{
levelstringoptionalУровень результата = ['ERROR', 'WARNING'],
messagestringoptionalСообщение,
fieldsArray[string]optionalНазвания полей (при наличии связи с моделью)
}
]
401 (Unauthorized Error)
CauseMessageDescription
UNAUTHORIZEDaccessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
403 (Forbidden)
CauseMessageDescription
ACTION_ACCESS_EXCEPTIONОперация не может быть выполнена: доступ к ресурсу запрещенИспользуемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция PAYMENT_REQUEST_OUT. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.
Вы использовали access_token пользователя Клиента, а не пользователя вашей организации. Нужно использовать access_token пользователя вашей организации.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
404 (Not found)
CauseMessageDescription
NOT_FOUNDДокумент с указанным ID не найден
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
500 (Internal Server Error)
CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
503 (Service Temporarily Unavailable)
CauseMessageDescription
UNAVAILABLE_RESOURCE_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

Статусы платежных требований

bankStatus (string)
Код состояние документаНаименование статусаНазначение кода состояния
Промежуточные статусы/Продолжать опрашивать
ACCEPTEDПринятЭлектронный документ принят на стороне Банка
ACCEPTED_BY_ABSПринят АБСЭлектронный документ был принят к обработке в АБС Банка
CARD2Картотека 2Электронный документ передан в картотеку в ожидание средств на счету клиента
CHECKERRORОшибка контроляЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
CREATEDСозданДокумент записан в БД, проверки не выполнялись
DELAYEDПриостановленОбработка электронного документа была приостановлена
DELIVEREDДоставленЗапрос доставлен в ДБО и взят в обработку
EXPORTEDВыгруженЭлектронный документ выгружен Банком в АБС
FRAUDALLOWОдобрен ФРОДПроверка во ФРОДЕ прошла успешно, переход на «Принят»
FRAUDDENYОтвергнут ФРОДДокумент отказан на основе проверки в АС Fraud-мониторинг, переходим в «Отвергнут банком»
FRAUDREVIEWНа проверке у специалиста БанкаСо стороны ФРОД-анализа получен статус документа «На проверке у специалиста Банка»
FRAUDSENTОтправлен во ФРОДДокумент отправлен на проверку в АС Fraud-мониторинг
FRAUDSMSТребуется подтверждение sms-паролемСо стороны ФРОД-анализа получен статус документа «Требуется подтверждение sms-паролем»
PARTSIGNEDЧастично подписанЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей
PROCESSINGВ обработкеКлиент сформировал «Заявление об акцепте/частичном акцепте/отказе от акцепта»
REQUESTED_RECALLЗапрошен отзывДокумент отозван
SENDED_TO_PAYERОтправлен плательщикуДокумент отправлен плательщику, который является клиентом Сбербанка
SIGNEDПодписанЭД подписан предусмотренным для него комплектом подписей
SUBMITTEDПредставленЭлектронный документ принят ВК
Окончательные статусы/Прекратить опрос
CHECKERROR_BANKОшибка контроля, БанкЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
DECLINED_BY_PAYERОтвергнут плательщикомДокумент отвергнут плательщиком
INVALIDEDSЭПАСП не вернаПроверка ЭП под ЭД на стороне Банка дала отрицательный результат
RECALLОтозванЭлектронный документ был отозван Клиентом по запросу
REFUSED_BY_RZKОтказан контролирующей организациейЭД не прошел проверки контролирующей организацией
REQUISITEERRORОшибка реквизитовВ ЭД указаны ошибочные реквизиты
REFUSEDBYABSОтказан АБСЭД не прошел проверки в АБС
Окончательные(Успешные) статусы/Прекратить опрос
IMPLEMENTEDИсполненЭлектронный документ исполнен Банком
SENDED_TO_PAYERОтправлен плательщикуДокумент отправлен плательщику, который не является клиентом Сбербанка

Дополнительная информация

Параметры НДС

Для корректной работы необходимо передавать параметры в следующем сочетании:

  • Если блок vat не указан, то по умолчанию будут присвоены и придут в ответе на запрос следующие значения:
"vat": {
  "type": "NO_VAT",
  "rate": "0",
  "amount": "0.00"
}

Важно

В поле "Назначение платежа" необходимо обязательно отправлять "НДС не облагается".

  • При выбранном "type":"INCLUDED" (НДС включен в сумму платежа) в атрибуте "amount" необходимо указать сумму НДС. Атрибут "rate" должен принимать только значения 10, 20. В поле "Назначение платежа" необходимо обязательно указать посчитанное значение НДС. Пример ПРАВИЛЬНОГО заполнения: НДС10%_-_100.63 рублей (нижнее подчеркивание является признаком пробела, символ проставлять не нужно). Если процентное значение не указано, то дефис перед суммой указывать не нужно: НДС_100.63 рублей.

  • При выбранном "type":"MANUAL" (Ручной ввод НДС) атрибут "amount" указывать не обязательно, но в этом случае по умолчанию сумма НДС примет значение 0 рублей. Если же атрибут "amount" указывается в запросе, то в нем нужно указать желаемое значение НДС, соответствующее формату. Если процентное значение не указано, то дефис перед суммой указывать не нужно: НДС_100.63 рублей.


FAQ

Будет ли исполнено Банком платежное требование , отправленное выходные или праздничные дни?

В выходные и праздничные дни платежи исполняются, если вы подключили расширенный режима счета. В него входят:

  • переводы на счета корпоративных клиентов и физических лиц внутри ПАО Сбербанк;
  • переводы в пользу контрагентов в других банках (в том числе в бюджет и на счета физических лиц);
  • переводы на основании документов, ранее помещенных в очередь не исполненных в срок распоряжений к банковскому счету клиента в пользу контрагентов (корпоративных клиентов и физических лиц) внутри ПАО Сбербанк (в том числе оплата задолженности, возникшей по комиссиям банка), а также в другие банки. Инструкция по подключению и отключению расширенного режима счета на странице помощи СберБизнеса.
Что происходит если денежных средств на счете клиента недостаточно?

В случае недостатка денежных средств на счете клиента для оплаты, платежное требование подлежит частичному исполнению (в сумме доступного остатка по банковскому счету плательщика), далее платежное требование помещается в очередь неисполненных в срок распоряжений и исполняется по мере поступления денежных средств в порядке очередности, установленной законодательством РФ. В данном случае вы получите промежуточный статус по платежному требованию CARD2 («Картотека»).
Необходимо продолжать спрашивать статус по платежному требованию до момента получения конечного статуса IMPLEMENTED («Исполнен»). Создавать новое платежное поручение и отправлять повторно Клиенту не требуется.

Может ли клиент отключить подписку?

Клиент может отменить подписку в СберБизнесе, отозвав согласие на заранее данный акцепт. В таком случае при вызове ресурса /v1/partner-info/advance-acceptances в поле "active" вы получите значение "false".

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.
Документация
SberJazzSaluteSpeechSaluteBotВся документация
Наши продукты
Витрина технологийБаза знанийСтань частью IT-команды
Юридические документы
Политика конфиденциальности Политика обработки данныхВсе соглашения и политики
© 1997–2024 ПАО СберБанк. Генеральная лицензия на осуществление банковских операций от 11 августа 2015 года. Регистрационный номер — 1481