ym88659208ym87991671
Платежные поручения | Документация для разработчиков

Платежные поручения

Обновлено 12 сентября 2024

Информация о продукте

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

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

Больше полезной информации о расчетах и платежах можно изучить на сайте Банка.


Схема работы продукта

Схема работы продукта

Авторизация

Все запросы в Sber API выполняются от имени конкретного пользователя СберБизнес, в том числе при интеграции для работы с информацией только по собственной компании. Запросы в Sber API в заголовке (Header) содержат параметр - Authorization. В нем требуется передавать токен доступа (access_token) пользователя. Получение токена доступа осуществляется с помощью сервиса СберБизнес ID. Подробно о подключении и работе сервиса авторизации рассказали в соответствующем разделе документации.

При интеграции по собственной компании потребуется выбрать одного пользователя СберБизнес и пройти им авторизацию через СберБизнес ID единоразово. В дальнейшем вам потребуется своевременно обновлять токен доступа при помощи токена обновления - обновить токен доступа.


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

Ниже будут приведены примеры реализации. Сценарии могут быть для вас отправной точкой и идеей для финального способа реализации функциональности.

Сценарии описали общие, для более легкого восприятия информации описания работы с продуктом Платежные поручения в Sber API.

Можно использовать разные триггеры запуска того или иного сценария - действия пользователя, регламентный запуск по времени, наступление определенных событий и другие варианты.

Варианты реализации
Осуществление перевода по расчетному счету

В схеме можно использовать автоматизированное подписание документа. Данная возможность доступна только при использовании ЭЦП сотрудника вашей компании.

Подробнее об использовании ЭЦП в Sber API можно почитать в одноименном разделе.

Шаги

  1. Получить реквизиты для формирования Платежного поручения
  2. Создать и подписать платежное поручение

Участники usecase

  • Пользователь - сотрудник вашей компании либо представитель ЮЛ/ИП, от лица которого он работает в рамках вашего сервиса (Платформа)
  • Платформа - любой web-ресурс (интернет-магазин, облачный сервис, мобильное приложение и т.д.) либо ваша внутренняя система (ERP, учетная система и др.), которую используют Пользователи
  • Sber API - в контексте usecase представляет из себя запросы и ресурсы Sber API, к которым обращается Платформа

Предусловия

  • Пользователь имеет пользовательский профиль в СберБизнес своей компании
  • Пользователь находится в пространстве Платформы
  • Пользователь прошел авторизацию с помощью СберБизнес ID

Постусловия

  • Создано и подписано платежное поручение
Осуществление перевода по расчетному счету

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

№МетодТочка вызоваОписаниеОперация в scopeШаг в схеме
1Alt text/fintech/api/v1/client-infoПолучение расширенной информацииGET_CLIENT_ACCOUNTS1. Получить реквизиты для формирования платежного поручения
2Alt text/ic/sso/api/v2/oauth/tokenОбновление токена доступаopenid1. Получить реквизиты для формирования платежного поручения
3Alt text/fintech/api/v1/paymentsСоздание рублёвого платёжного порученияPAY_DOC_RU2. Создать и подписать платежное поручение
Проверка статуса и корректности оплаты

Время начала и частоту проверки статуса и корректности оплаты вы определяете самостоятельно исходя из своих бизнес-задач.

Шаги

  1. Получить статус оплаты
  2. Проверить корректность

Участники usecase

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

Предусловия

  • Успешно выполнен сценарий "Осуществление перевода по расчетному счету"
  • Платформа сохранила идентификатор (extertalId) платежного поручения, созданного в рамках сценария "Осуществление перевода по расчетному счету"

Постусловия

  • Платежное поручение оплачено
  • Проверена корректность проведенной оплаты
Проверка статуса и корректности оплаты
№МетодТочка вызоваОписаниеОперация в scopeШаг в схеме
1Alt text/fintech/api/v1/payments/{externalId}/stateПолучение статуса рублёвого платёжного порученияPAY_DOC_RU1. Получить статус оплаты
2Alt text/ic/sso/api/v2/oauth/tokenОбновление токена доступаopenid1. Получить статус оплаты
3Alt text/fintech/api/v1/payments/{externalId}Получение платёжного порученияPAY_DOC_RU2. Проверить корректность

Создание рублёвого платёжного поручения

Alt text /fintech/api/v1/payments

Запрос позволяет создать рублёвое платёжное поручение (далее РПП).

Для создания РПП необходимо отправить POST-запрос /fintech/api/v1/payments с токеном доступа (access_token) пользователя в параметре Authorization заголовка и реквизитами документа в теле запроса.

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


  • Если в запросе на создание платежного документа передать ЭП к документу (объект digestSignatures), то Банк сразу начнет обработку документа.
  • Если в запросе не передавать ЭП к документу, то платежное поручение будет создано в статусе черновик. Для начала обработки документа Банком потребуется зайти в интерфейс СберБизнес и подписать его.

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

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

Request

/fintech/api/v1/payments
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^[a-zA-Z0-9]{38}$requiredAccess token пользователя, полученный через SSO.
BODY
Invoice {
  amountnumberfloat^[0-9]{1,16}\.[0-9]{2}$requiredСумма платежа,
  datestringISO 8601 YYYY-MM-DD^[0-9]{4}-[0-9]{2}-[0-9]{2}$requiredДата составления документа,
  deliveryKindstringstring^(электронно|срочно|0)$optionalВид платежа.
Если не заполнено или 0, то будет присвоено значение "электронно",
  departmentalInfoDepartmentalInfoobjectoptionalРеквизиты налогового, таможенного или иного бюджетного платежа,
  digestSignaturesarray[Signature]arrayoptionalЭлектронные подписи по дайджесту документа.
- Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
- Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес.

О подписании дайджеста платежного документа подробно рассказали в соответствующем разделе документации.
  externalIdstringUUID^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$requiredИдентификатор документа, который вы присваиваете самостоятельно,
  incomeTypeCodestringstring^[1-9]{1,6}$optionalКод вида дохода получателей выплаты по 229-ФЗ.

Коды:
1 - Заработная плата и иные доходы, в отношении которых ст. 99 229-ФЗ установлены ограничения размеров удержания.
2 - Периодические доходы, на которые в соответствии с ч. 1 ст. 101 229-ФЗ не может быть обращено взыскание, за исключением доходов, указанных в ч. 2 ст. 101 229-ФЗ.
3 - Периодические доходы, к которым согласно ч. 2 ст. 101 229-ФЗ ограничения по взысканию не применяются.
4 - Единовременный доход, на который в соответствии с ч. 1 ст. 101 229-ФЗ не может быть обращено взыскание, за исключением доходов, указанных в ч. 2 ст. 101 229-ФЗ.
5 - Единовременный доход, к которому согласно ч. 2 ст. 101 229-ФЗ ограничения по взысканию не применяются.
null - Код дохода указывать не нужно, если денежные средства не относятся к доходам с установленными ограничениями согласно ст. 99 и запретом согласно ст. 101 229-ФЗ,
  numberstringstring^[0-9]{1,6}$optionalНомер документа,
  operationCodestringstring^01$requiredКод операции,
  payeeAccountstringstring^[0-9]{20}$optionalСчет получателя платежа,
  payeeBankBicstringstring^[0-9]{9}$requiredБИК получателя платежа,
  payeeBankCorrAccountstringstring^[0-9]{20}$optionalКорсчет банка получателя платежа,
  payeeInnstringstring^([0-9]{5}|[0-9]{10}|[0-9]{12}|0)$optionalИНН получателя платежа,
  payeeKppstringstring^([0-9]{9}|0)$optionalКПП получателя платежа,
  payeeNamestringstring^.{1,254}$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ИНН плательщика,
  payerKppstringstring^([0-9]{9}|0)$requiredКПП плательщика,
  payerNamestringstring^.{1,254}$requiredПолное наименование плательщика,
  prioritystringstring^(1|2|3|4|5)$requiredОчередность платежа,
  purposestringstring^.{1,210}$requiredНазначение платежа.

Рекомендации по заполнению,
  urgencyCodestringstring^(INTERTAL|INTERNAL_NOTIF|OFFHOURS|BESP|NORMAL)$optionalКод срочности.

INTERNAL - срочный
INTERNAL_NOTIF - срочный платеж с уведомлением
OFFHOURS - неотложный
BESP - банковские электронные срочные платежи
NORMAL - срочность не указана,
  vatVatobjectoptionalДанные НДС,
  voCodestringstring^[0-9]{5}$optionalКод вида валютной операции
}
DepartmentalInfo {
  uipstringstring^[A-Za-z0-9]{1,25}$requiredУникальный идентификатор платежа,
  drawerStatus101stringstring^(01|02|08|13)$requiredПоказатель статуса налогоплательщика (реквизит - 101),
  kbkstringstring^[A-Za-z0-9]{1,20}$requiredКод бюджетной классификации (реквизит - 104),
  oktmostringstring^[A-Za-z0-9]{1,11}$requiredКод OKTMO (реквизит - 105),
  reasonCode106stringstring^[0-9]{1,2}$requiredПоказатель основания платежа (реквизит - 106),
  taxPeriod107stringstring^(0|[0-9]{8}|([0-9]{2}|МС|КВ|ПЛ|ГД)\.[0-9]{2}\.[0-9]{4})$requiredНалоговый период / код таможенного органа (реквизит - 107),
  docNumber108stringstring^[0-9]{1,15}$requiredНомер налогового документа (реквизит - 108),
  docDate109stringstring^(0|00|[0-9]{2}.[0-9]{2}.[0-9]{4})$requiredДата налогового документа (реквизит - 109),
  paymentKind110stringstring^[0-9]{1,2}$optionalТип налогового платежа (реквизит - 110)
}
Signature {
  base64Encodedstringbase64^[a-zA-Z0-9]+$requiredЗначение электронной подписи (ЭП), закодированное в Base64,
  certificateUuidstringUUID^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$requiredУникальный идентификатор сертификата ключа проверки электронной подписи
}
Vat {
  amountnumberfloat^[0-9]{1,16}\.[0-9]{2}$optionalСумма НДС,
  ratestringstring^[0-9]{0,2}$optionalСтавка НДС,
  typestringstring^(INCLUDED|NO_VAT|MANUAL)$requiredСпособ расчета НДС.

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

digestSignatures

Формат дайджеста
Наименование поляОписание поляПример
amountСумма платежа100.00
dateДата составления документа2018-05-31
departmentalInfo.docNumber108Номер налогового документа(реквизит-108)123
departmentalInfo.drawerStatus101Показатель статуса налогоплательщика(реквизит-101)01
departmentalInfo.kbkКод бюджетной классификации(реквизит-104)18210102010011000110
departmentalInfo.oktmoКод ОКТМО(реквизит-105)1701000
departmentalInfo.paymentKind110Тип налогового платежа(реквизит-110)НС
departmentalInfo.reasonCode106Показатель основания платежа(реквизит-106)ТП
departmentalInfo.uipУникальный идентификатор платежа0
externalIdИдентификатор документа, присвоенный сервисомa0000000-0000-0000-0000-000000000001
incomeTypeCodeКод вида дохода получателей выплаты по 229-ФЗ2
operationCodeКод операции01
payeeAccountНомер счета получателя40702810600100001212
payeeBankBicБИК получателя044525225
payeeBankCorrAccountКорсчет банка получателя30101810400000000225
payeeInnИнн получателя222201236445
payeeKppКпп получателя222201001
payeeNameПолное наименование получателя платежаОбщество с ограниченной ответственностью "Получатель"
payerAccountСчет плательщика40702810500006103990
payerBankBicБИК плательщика044525225
payerBankCorrAccountКорсчет банка плательщика30101810400000000225
payerInnИНН плательщика222201236445
payerKppКПП плательщика222201001
payerNameПолное наименование плательщикаОбщество с ограниченной ответственностью "Клиент"
priorityОчередность платежа5
purposeНазначение платежаОплата интернет заказа №123. НДС нет.
voCodeКод вида валютной операции61150

Responses

201 (Created)
НаименованиеТипОбязательностьОписание
Invoice {
  amountnumberrequiredСумма платежа,
  bankCommentstringoptionalБанковский комментарий к статусу документа,
  bankStatusstringoptionalСтатус документа,
  crucialFieldsHashstringoptionalHash от ключевых полей документа,
  datestringrequiredДата составления документа,
  deliveryKindstringoptionalВид платежа,
  departmentalInfoDepartmentalInfooptionalРеквизиты налогового, таможенного или иного бюджетного платежа,
  digestSignaturesarray[Signature]optionalЭлектронные подписи по дайджесту документа,
  externalIdstringrequiredИдентификатор документа, который вы присваиваете самостоятельно,
  incomeTypeCodestringoptionalКод вида дохода получателей выплаты по 229-ФЗ,
  numberstringoptionalНомер документа,
  operationCodestringrequiredКод операции,
  payeeAccountstringoptionalСчет получателя платежа,
  payeeBankBicstringrequiredБИК получателя платежа,
  payeeBankCorrAccountstringoptionalКорсчет банка получателя платежа,
  payeeInnstringoptionalИНН получателя платежа,
  payeeKppstringoptionalКПП получателя платежа,
  payeeNamestringrequiredПолное наименование получателя платежа,
  payerAccountstringrequiredСчет плательщика,
  payerBankBicstringrequiredБИК банка плательщика,
  payerBankCorrAccountstringrequiredКорсчет банка плательщика,
  payerInnstringrequiredИНН плательщика,
  payerKppstringrequiredКПП плательщика,
  payerNamestringrequiredПолное наименование плательщика,
  prioritystringrequiredОчередность платежа,
  purposestringrequiredНазначение платежа,
  urgencyCodestringoptionalКод срочности,
  vatVatoptionalДанные НДС,
  voCodestringoptionalКод вида валютной операции
}
DepartmentalInfo {
  uipstringrequiredУникальный идентификатор платежа,
  drawerStatus101stringrequiredПоказатель статуса налогоплательщика (реквизит - 101),
  kbkstringrequiredКод бюджетной классификации (реквизит - 104),
 oktmostringrequiredКод OKTMO (реквизит - 105),
  reasonCode106stringrequiredПоказатель основания платежа (реквизит - 106),
  taxPeriod107stringrequiredНалоговый период / код таможенного органа (реквизит - 107),
  docNumber108stringrequiredНомер налогового документа (реквизит - 108),
  docDate109stringrequiredДата налогового документа (реквизит - 109),
  paymentKind110stringoptionalТип налогового платежа (реквизит - 110)
}
Signature {
  base64EncodedstringrequiredЗначение электронной подписи (ЭП), закодированное в Base64,
  certificateUuidstringrequiredУникальный идентификатор сертификата ключа проверки электронной подписи
}
Vat {
  amountnumberoptionalСумма НДС,
  ratestringoptionalСтавка НДС,
  typestringrequiredСпособ расчета НДС
}
400 (Bad request)
CauseMessageDescription
DESERIALIZATION_FAULTНеверный формат запросаДанные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
WORKFLOW_FAULTДля внешнего сервиса недоступны операции по счету: {номер счета}Возможные причины ошибки:
счет не добавлен в список разрешенных в оферте;
внешний сервис заблокирован в СберБизнес;
счет указан неверно;
отсутствует доступный открытый рублевый расчетный счет у организации плательщика
Отсутствует возможность подписи документа, сумма превышает дневной лимитНеобходимо в UI СберБизнес изменить настройли дневного лимита переводов для пользователя
Невозможно идентифицировать банк плательщика по указанным номеру БИК и корреспондентскому счетуПроверьте корректность заполнения атрибутов payerBankBic и payerBankCorrAccount
Невозможно идентифицировать банк получателя по указанным номеру БИК и корреспондентскому счетуПроверьте корректность заполнения атрибутов payeeBankBic и payeeBankCorrAccount
Документ с таким externalId уже существует в системеСгенерируйте новый UUID для атрибута externalId и выполните запрос повторно
{Наименование криптопрофиля}: не найдено действующих полномочий подписиУ Пользователя, чей access_token используется в зарпосе создания платежного поручения, отсутствует право подписи документов в СберБизнес. Проверьте настройки профиля Пользователя в UI СберБизнес. Либо получите access_token другим профилем Пользователя, который имеет право подписи в СберБизнес.
{Наименование криптопрофиля}: некорректные настройки полномочий подписи
{Наименование криптопрофиля}: нет полномочий для подписи документа в рамках организации {Наименование организации}
{Наименование криптопрофиля}: нет полномочий для подписи документа по счету {Номер счета}
{Наименование криптопрофиля}: нет полномочий для подписи документа {Наименование типа документа}
{Наименование криптопрофиля}: нет полномочий для подписи документа {Наименование типа документа} на сумму, превышающую {сумма лимита}
ЭП не может быть принята
Не предусмотрено сохранение более двух ЭП под документом
Не предусмотрено указание будущей даты в документе с ЭП
VALIDATION_FAULTОбъект {название объекта} не соответствует моделиДанные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
SIGN_CHECK_EXCEPTIONПодлинность подписи не установлена/Сертификат не обнаружен или не является активным
НаименованиеТипОбязательностьОписание
ResourceFault {
  causestringoptionalПричина или основание сообщения,
  referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
  messagestringoptionalСообщение,
  checksarray[Check]optionalСписок проверок, приведших к ошибке,
  fieldNamesarray[string]optionalНазвания полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
  levelstringoptionalУровень результата = ['ERROR', 'WARNING'],
  messagestringoptionalСообщение,
  fieldsarray[string]optionalНазвания полей (при наличии связи с моделью)
}
403 (Forbidden)
CauseMessageDescription
ACTION_ACCESS_EXCEPTIONОперация не может быть выполнена: доступ к ресурсу запрещенИспользуемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция PAY_DOC_RU. Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_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Сообщение,
}

Получение статуса рублёвого платёжного поручения

Alt text /fintech/api/v1/payments/{externalId}/state

Запрос позволяет получить статус ранее созданного платёжного поручения.

Для получения статуса платёжного поручения необходимо отправить GET-запрос /fintech/api/v1/payments/{externalId}/state с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатор документа (externalId) в path-параметре.

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

  • PAY_DOC_RU
  • PAY_DOC_RU_INVOICE
  • PAY_DOC_RU_INVOICE_ANY
  • PAY_DOC_RU_INVOICE_BUDGET

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

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

Request

/fintech/api/v1/payments/{externalId}/state
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^[a-zA-Z0-9]{38}$requiredAccess token пользователя, полученный через SSO.
Acceptstringstring^(application/json|application/jose)optionalУказывает на формат данных, который вы готовы принять от Банка.
- Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json.
- Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
PATH PARAMETERS
externalIdstringUUID^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$requiredИдентификатор документа, присвоенный вами при создании документа

Responses

200 (ОК)
НаименованиеТипОбязательностьОписание
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, не указана ни одна из операций по работе с платежными поручениями (PAY_DOC_RU, PAY_DOC_RU_INVOICE, PAY_DOC_RU_INVOICE_ANY или PAY_DOC_RU_INVOICE_BUDGET). Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_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 или
Ожидает оплаты		АБС обнаружено, что на счете плательщика недостаточно средств для иcполнения документа
CREATEDСозданДокумент записан в БД, проверки не выполнялись
CHECKERRORОшибка контроляЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
DELAYEDПриостановленОбработка электронного документа была приостановлена
DELIVEREDДоставленЗапрос доставлен в ДБО и взят в обработку
DELIVERED_RZKДоставлен в СБКЭлектронный документ отправлен в СБК и получен квиток о доставке
FRAUDALLOWОдобрен ФРОДПроверка во ФРОДЕ прошла успешно, переход на «Принят»
FRAUDREVIEWНа проверке у специалиста БанкаСо стороны ФРОД-анализа получен статус документа «На проверке у специалиста Банка»
FRAUDSENTОтправлен во ФРОДДокумент отправлен на проверку в АС Fraud-мониторинг
FRAUDSMSТребуется подтверждение sms-паролемСо стороны ФРОД-анализа получен статус документа «Требуется подтверждение sms-паролем»
NOT_ACCEPTED_RZKНе принят СБКЭлектронный документ не прошел логические контроли СБК
PARTSIGNEDЧастично подписанЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей
PROCESSING_RZKОбрабатывается СБКЭД успешно прошел проверки ЭП и логические проверки СБК
REQUESTED_RECALLЗапрошен отзывДокумент отозван
RZK_SIGN_ERRORОшибка ЭП СБКПроверка подписи под ЭД на стороне СБК дала отрицательный результат
SENDING_TO_RZKОтправляется в СБКЭлектронный документ отправлен в СБК, но не получен квиток о доставке
SIGNEDПодписанЭД подписан предусмотренным для него комплектом подписей.
TO_PROCESSING_RZKК отправке в СБКЭД подписан предусмотренным для него комплектом о доставке
Окончательный (Не успешный)/Прекратить опрос
DELETEDУдаленЭлектронный документа удален из числа действующих документов
INVALIDEDSЭП/АСП не верна
Подпись неверна		Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
RECALLОтозванЭлектронный документ был отозван Клиентом по запросу
REFUSEDBYBANKОтвергнут банком или
Отклонен банком		Электронный документ отвергнут банком
REFUSEDBYABSОтказан АБСЭлектронный документ не прошел проверки в АБС
REQUISITEERRORОшибка реквизитовВ ЭД указаны ошибочные реквизиты
REFUSED_BY_RZKОтказан контролирующей организациейЭлектронный документ не прошел проверки контролирующей организацией
FRAUDDENYОтвергнут ФРОДДокумент отказан на основе проверки в АС Fraud-мониторинг, переходим в «Отвергнут банком»
Окончательный (Успешный)/Прекратить опрос
IMPLEMENTEDИсполненЭлектронный документ исполнен Банком

Получение платёжного поручения

Alt text /fintech/api/v1/payments/{externalId}

Запрос позволяет получить полные данные ранее созданного платёжного поручения.

Для получения полных данных платёжного поручения необходимо отправить GET-запрос /fintech/api/v1/payments/{externalId} с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатор документа (externalId) в path-параметре.

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

  • PAY_DOC_RU
  • PAY_DOC_RU_INVOICE
  • PAY_DOC_RU_INVOICE_ANY
  • PAY_DOC_RU_INVOICE_BUDGET

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

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

Request

/fintech/api/v1/payments/{externalId}
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^[a-zA-Z0-9]{38}$requiredAccess token пользователя, полученный через SSO.
Acceptstringstring^(application/json|application/jose)optionalУказывает на формат данных, который вы готовы принять от Банка.
- Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json.
- Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
PATH PARAMETERS
externalIdstringUUID^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$requiredИдентификатор документа, присвоенный вами при создании документа

Responses

200 (ОК)
НаименованиеТипОбязательностьОписание
Payment {
  amountnumberrequiredСумма платежа,
  bankCommentstringoptionalБанковский комментарий к статусу документа,
  bankStatusstringoptionalСтатус документа,
  crucialFieldsHashstringoptionalHash от ключевых полей документа,
  datestringrequiredДата составления документа,
  deliveryKindstringoptionalВид платежа,
  departmentalInfoDepartmentalInfooptionalРеквизиты налогового, таможенного или иного бюджетного платежа,
  digestSignaturesarray[Signature]optionalЭлектронные подписи по дайджесту документа,
  externalIdstringrequiredИдентификатор документа, присвоенный партнером,
  incomeTypeCodestringoptionalКод вида дохода получателей выплаты по 229-ФЗ,
  numberstringoptionalНомер документа,
  operationCodestringrequiredКод операции,
  payeeAccountstringoptionalСчет получателя платежа,
  payeeBankBicstringrequiredБИК получателя платежа,
  payeeBankCorrAccountstringoptionalКорсчет банка получателя платежа,
  payeeInnstringoptionalИНН получателя платежа,
  payeeKppstringoptionalКПП получателя платежа,
  payeeNamestringrequiredПолное наименование получателя платежа,
  payerAccountstringrequiredСчет плательщика,
  payerBankBicstringrequiredБИК банка плательщика,
  payerBankCorrAccountstringrequiredКорсчет банка плательщика,
  payerInnstringrequiredИНН плательщика,
  payerKppstringoptionalКПП плательщика,
  payerNamestringrequiredПолное наименование плательщика,
  prioritystringrequiredОчередность платежа,
  purposestringrequiredНазначение платежа,
  urgencyCodestringoptionalКод срочности,
  vatvatoptionalДанные НДС,
  voCodestringoptionalКод вида валютной операции
}
DepartmentalInfo {
  uipstringrequiredУникальный идентификатор платежа,
  drawerStatus101stringrequiredПоказатель статуса налогоплательщика (реквизит - 101),
  kbkstringrequiredКод бюджетной классификации (реквизит - 104),
  oktmostringrequiredКод OKTMO (реквизит - 105),
  reasonCode106stringrequiredПоказатель основания платежа (реквизит - 106),
  taxPeriod107stringrequiredНалоговый период / код таможенного органа (реквизит - 107),
  docNumber108stringrequiredНомер налогового документа (реквизит - 108),
  docDate109stringrequiredДата налогового документа (реквизит - 109),
  paymentKind110stringoptionalТип налогового платежа (реквизит - 110)
}
Signature {
  base64EncodedstringrequiredЗначение электронной подписи, закодированное в Base64,
  certificateUuidstringrequiredУникальный идентификатор сертификата ключа проверки электронной подписи (UUID),
}
Vat {
  amountnumberoptionalСумма НДС,
  ratestringoptionalСтавка НДС,
  typestringrequiredСпособ расчета НДС
}
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, не указана ни одна из операций по работе с платежными поручениями (PAY_DOC_RU, PAY_DOC_RU_INVOICE, PAY_DOC_RU_INVOICE_ANY или PAY_DOC_RU_INVOICE_BUDGET). Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_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Сообщение,
}

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

Назначение платежа

Назначение должно раскрывать экономический смысл платежа.

  • Сведения должны быть лаконичными — у поля есть ограничения по знакам 210 символов.
  • В назначении необходимо указать реквизиты документа, по которому вы осуществляете платеж, например, номер договора или счета.
  • Рекомендуем указывать конкретный предмет оплаты.
  • Если платеж с НДС, необходимо прописать точную сумму налога.
    Ниже подробнее рассказали о формировании информации об НДС в назначении платежа.

Рекомендуемый вариант заполнения:

Оплата по договору [номер договора] от [дата договора]. НДС [ставка НДС]% - [сумма НДС] рубля [способ расчета НДС]. [Любая ваша информация]

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

Чтобы все работало правильно, нужно передать такие параметры:

  • Если НДС не указан, то по умолчанию будут использованы эти значения:
    "vat": {
      "type": "NO_VAT",
      "rate": "0",
      "amount": "0.00"
    }
    Важно: в поле «Назначение платежа» обязательно укажите НДС не облагается.
  • Если выбрали «type» — INCLUDED (НДС включен в сумму платежа), то в поле «amount» укажите сумму НДС. Значение «rate» должно быть 10 или 20. В поле «Назначение платежа» обязательно укажите посчитанную сумму НДС. Пример правильного заполнения: НДС 10% — 100.63 рубля (пробел обозначается нижним подчеркиванием, символ не ставится). Если процентное значение не указано, то дефис перед суммой ставить не нужно: НДС 100.63 рубля.
  • Если выбрали «type» — MANUAL (ввод НДС вручную), то поле «amount» заполнять необязательно, но по умолчанию сумма НДС будет равна нулю. Если же поле «amount» заполнено, то укажите нужную сумму НДС в соответствии с форматом. Если процентное значение не указано, то дефис перед суммой ставить не нужно: НДС 100.63 рубля.
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.