Платежные поручения
Информация о продукте
Платежное поручение – это документ, который используется для указания банку перевести определенную сумму денег с одного счета на другой. Обычно это делается, когда компания хочет произвести оплату за товары или услуги, перевести деньги индивидуальному предпринимателю или юридическому лицу.
Платежные поручения используются широким кругом лиц, включая индивидуальных предпринимателей, малый и средний бизнес, крупные корпорации и даже государственные учреждения. Их используют, когда нужно сделать перевод, который требует предварительного уведомления или планирования (например, оплата аренды, коммунальных услуг или выплата заработной платы).
Больше полезной информации о расчетах и платежах можно изучить на сайте Банка.
Схема работы продукта
- Графическое описание
- Текстовое описание
# | Что делаем | Подробности |
---|---|---|
1 | Авторизуйте Пользователя с помощью СберБизнес ID | Подробно о подключении и работе сервиса СберБизнес ID рассказали в соответствующем разделе документации. |
2 | Получите реквизиты для формирования Платежного поручения | Запрос /fintech/api/v1/client-info и токен доступа (access_token) Пользователя позволит вам получить часть реквизитов для создания платежного поручения, в частности информацию о доступных счетах для списания денежных средств.Предоставьте Пользователю в UI вашей платформы заполнить реквизиты получателя платежа. Теперь у вас есть вся необходимая информация для создания платежного поручения. Можно переходить к следующему шагу. |
3 | Создайте и подпишите платежное поручение | Запрос /fintech/api/v1/payments и токен доступа (access_token) Пользователя позволит создать Платежное поручение в СберБизнес Пользователя.Если вместе с запросом передать ЭП к документу, то Банк сразу начнет обработку документа. У вас есть возможность автоматизировать подписание платежных документов в API - подробно о работе с ЭЦП рассказали в соответствующем разделе документации. Если запрос передать без ЭП к документу, в СберБизнес будет создан черновик Платежного поручения. Пользователю дополнительно потребуется перейти в UI СберБизнес и подписать документ. |
4 | Проверьте статус и корректность оплаты | С помощью запроса /fintech/api/v1/payments/{externalId}/state вы сможете разработать механизм проверки статуса оплаты и реакцию Платформы на каждый из них.С помощью запроса /fintech/api/v1/payments/{externalId} вы сможете получить все параметры ранее созданного платежного поручения. Эту информацию можно использовать, например, в механизме проверки корректности платежа. |
Авторизация
Все запросы в Sber API выполняются от имени конкретного пользователя СберБизнес, в том числе при интеграции для работы с информацией только по собственной компании. Запросы в Sber API в заголовке (Header) содержат параметр - Authorization. В нем требуется передавать токен доступа (access_token) пользователя. Получение токена доступа осуществляется с помощью сервиса СберБизнес ID. Подробно о подключении и работе сервиса авторизации рассказали в соответствующем разделе документации.
При интеграции по собственной компании потребуется выбрать одного пользователя СберБизнес и пройти им авторизацию через СберБизнес ID единоразово. В дальнейшем вам потребуется своевременно обновлять токен доступа при помощи токена обновления - обновить токен доступа.
Варианты реализации
Ниже будут приведены примеры реализации. Сценарии могут быть для вас отправной точкой и идеей для финального способа реализации функциональности.
Сценарии описали общие, для более легкого восприятия информации описания работы с продуктом Платежные поручения в Sber API.
Можно использовать разные триггеры запуска того или иного сценария - действия пользователя, регламентный запуск по времени, наступление определенных событий и другие варианты.
Осуществление перевода по расчетному счету
В схеме можно использовать автоматизированное подписание документа. Данная возможность доступна только при использовании ЭЦП сотрудника вашей компании.
Подробнее об использовании ЭЦП в Sber API можно почитать в одноименном разделе.
Шаги
- Получить реквизиты для формирования Платежного поручения
- Создать и подписать платежное поручение
Участники usecase
- Пользователь - сотрудник вашей компании либо представитель ЮЛ/ИП, от лица которого он работает в рамках вашего сервиса (Платформа)
- Платформа - любой web-ресурс (интернет-магазин, облачный сервис, мобильное приложение и т.д.) либо ваша внутренняя система (ERP, учетная система и др.), которую используют Пользователи
- Sber API - в контексте usecase представляет из себя запросы и ресурсы Sber API, к которым обращается Платформа
Предусловия
- Пользователь имеет пользовательский профиль в СберБизнес своей компании
- Пользователь находится в пространстве Платформы
- Пользователь прошел авторизацию с помощью СберБизнес ID
Постусловия
- Создано и подписано платежное поручение
Используемые запросы
№ | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
---|---|---|---|---|---|
1 | /fintech/api/v1/client-info | Получение расширенной информации | GET_CLIENT_ACCOUNTS | 1. Получить реквизиты для формирования платежного поручения | |
2 | /ic/sso/api/v2/oauth/token | Обновление токена доступа | openid | 1. Получить реквизиты для формирования платежного поручения | |
3 | /fintech/api/v1/payments | Создание платежного поручения | PAY_DOC_RU | 2. Создать и подписать платежное поручение |
Проверка статуса и корректности оплаты
Время начала и частоту проверки статуса и корректности оплаты вы определяете самостоятельно исходя из своих бизнес-задач.
Шаги
- Получить статус оплаты
- Проверить корректность
Участники usecase
- Платформа - любой web-ресурс (интернет-магазин, облачный сервис, мобильное приложение и т.д.) либо ваша внутренняя система (ERP, учетная система и др.), которую используют Пользователи
- Sber API - в контексте usecase представляет из себя запросы и ресурсы Sber API, к которым обращается Платформа
Предусловия
- Успешно выполнен сценарий "Осуществление перевода по расчетному счету"
- Платформа сохранила идентификатор (extertalId) платежного поручения, созданного в рамках сценария "Осуществление перевода по расчетному счету"
Постусловия
- Платежное поручение оплачено
- Проверена корректность проведенной оплаты
№ | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
---|---|---|---|---|---|
1 | /fintech/api/v1/payments/{externalId}/state | Получение статуса платежного поручения | PAY_DOC_RU | 1. Получить статус оплаты | |
2 | /ic/sso/api/v2/oauth/token | Обновление токена доступа | openid | 1. Получить статус оплаты | |
3 | /fintech/api/v1/payments/{externalId} | Получение полных данных платежного поручения | PAY_DOC_RU | 2. Проверить корректность |
Создание платежного поручения
/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 | |||||
Authorization | string | string | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
BODY | |||||
Invoice { | |||||
amount | number | float | ^[0-9]{1,16}\.[0-9]{2}$ | required | Сумма платежа, |
date | string | ISO 8601 YYYY-MM-DD | ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ | required | Дата составления документа, |
deliveryKind | string | string | ^(электронно|срочно|0)$ | optional | Вид платежа. Если не заполнено или 0, то будет присвоено значение "электронно", |
departmentalInfo | DepartmentalInfo | object | optional | Реквизиты налогового, таможенного или иного бюджетного платежа, | |
digestSignatures | array[Signature] | array | optional | Электронные подписи по дайджесту документа. - Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу. - Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес. О подписании дайджеста платежного документа подробно рассказали в соответствующем разделе документации. | |
externalId | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | required | Идентификатор документа, который вы присваиваете самостоятельно, |
incomeTypeCode | string | string | ^[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-ФЗ, |
number | string | string | ^[0-9]{1,6}$ | optional | Номер документа, |
operationCode | string | string | ^01$ | required | Код операции, |
payeeAccount | string | string | ^[0-9]{20}$ | optional | Счет получателя платежа, |
payeeBankBic | string | string | ^[0-9]{9}$ | required | БИК получателя платежа, |
payeeBankCorrAccount | string | string | ^[0-9]{20}$ | optional | Корсчет банка получателя платежа, |
payeeInn | string | string | ^([0-9]{5}|[0-9]{10}|[0-9]{12}|0)$ | optional | ИНН получателя платежа, |
payeeKpp | string | string | ^([0-9]{9}|0)$ | optional | КПП получателя платежа, |
payeeName | string | string | ^.{1,254}$ | required | Полное наименование получателя платежа, |
payerAccount | string | string | ^[0-9]{20}$ | required | Счет плательщика, |
payerBankBic | string | string | ^[0-9]{9}$ | required | БИК банка плательщика, |
payerBankCorrAccount | string | string | ^[0-9]{20}$ | required | Корсчет банка плательщика, |
payerInn | string | string | ^([0-9]{5}|[0-9]{10}|[0-9]{12}|0)$ | required | ИНН плательщика, |
payerKpp | string | string | ^([0-9]{9}|0)$ | required | КПП плательщика, |
payerName | string | string | ^.{1,254}$ | required | Полное наименование плательщика, |
priority | string | string | ^(1|2|3|4|5)$ | required | Очередность платежа, |
purpose | string | string | ^.{1,210}$ | required | Назначение платежа. Рекомендации по заполнению, |
urgencyCode | string | string | ^(INTERTAL|INTERNAL_NOTIF|OFFHOURS|BESP|NORMAL)$ | optional | Код срочности. INTERNAL - срочный INTERNAL_NOTIF - срочный платеж с уведомлением OFFHOURS - неотложный BESP - банковские электронные срочные платежи NORMAL - срочность не указана, |
vat | Vat | object | optional | Данные НДС, | |
voCode | string | string | ^[0-9]{5}$ | optional | Код вида валютной операции |
} | |||||
DepartmentalInfo { | |||||
uip | string | string | ^[A-Za-z0-9]{1,25}$ | required | Уникальный идентификатор платежа, |
drawerStatus101 | string | string | ^(01|02|08|13)$ | required | Показатель статуса налогоплательщика (реквизит - 101), |
kbk | string | string | ^[A-Za-z0-9]{1,20}$ | required | Код бюджетной классификации (реквизит - 104), |
oktmo | string | string | ^[A-Za-z0-9]{1,11}$ | required | Код OKTMO (реквизит - 105), |
reasonCode106 | string | string | ^[0-9]{1,2}$ | required | Показатель основания платежа (реквизит - 106), |
taxPeriod107 | string | string | ^(0|[0-9]{8}|([0-9]{2}|МС|КВ|ПЛ|ГД)\.[0-9]{2}\.[0-9]{4})$ | required | Налоговый период / код таможенного органа (реквизит - 107), |
docNumber108 | string | string | ^[0-9]{1,15}$ | required | Номер налогового документа (реквизит - 108), |
docDate109 | string | string | ^(0|00|[0-9]{2}.[0-9]{2}.[0-9]{4})$ | required | Дата налогового документа (реквизит - 109), |
paymentKind110 | string | string | ^[0-9]{1,2}$ | optional | Тип налогового платежа (реквизит - 110) |
} | |||||
Signature { | |||||
base64Encoded | string | base64 | ^[a-zA-Z0-9]+$ | required | Значение электронной подписи (ЭП), закодированное в Base64, |
certificateUuid | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | required | Уникальный идентификатор сертификата ключа проверки электронной подписи |
} | |||||
Vat { | |||||
amount | number | float | ^[0-9]{1,16}\.[0-9]{2}$ | optional | Сумма НДС, |
rate | string | string | ^[0-9]{0,2}$ | optional | Ставка НДС, |
type | string | string | ^(INCLUDED|NO_VAT|MANUAL)$ | required | Способ расчета НДС. INCLUDED - НДС включен в сумму платежа NO_VAT - не облагается НДС MANUAL - ручной ввод НДС |
} |
POST /fintech/api/v1/payments HTTP/1.1
Accept: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
{
"number": "1",
"date": "2024-08-31",
"digestSignatures": [
{
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w=="
}
],
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"amount": 1.01,
"operationCode": "01",
"deliveryKind": "электронно",
"priority": "5",
"urgencyCode": "string",
"voCode": "61150",
"purpose": "Оплата заказа №123. НДС нет.",
"departmentalInfo": {
"uip": "0",
"drawerStatus101": "1",
"kbk": "18210102010011000000",
"oktmo": "1701000",
"reasonCode106": "ТП",
"taxPeriod107": "ГД.00.2018",
"docNumber108": "123",
"docDate109": "18210102010011000000",
"paymentKind110": "18210102010011000000"
},
"payerName": "string",
"payerInn": "7707083893",
"payerKpp": "222201001",
"payerAccount": "40802810600000200000",
"payerBankBic": "044525225",
"payerBankCorrAccount": "30101810400000000225",
"payeeName": "string",
"payeeInn": "7707083893",
"payeeKpp": "222201001",
"payeeAccount": "40802810600000200000",
"payeeBankBic": "044525225",
"payeeBankCorrAccount": "30101810400000000225",
"vat": {
"type": "NO_VAT",
"rate": "10",
"amount": 1.01
},
"incomeTypeCode": "2"
}
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 |
amount=100.00
date=2018-05-31
departmentalInfo.docNumber108=123
departmentalInfo.drawerStatus101=01
departmentalInfo.kbk=18210102010011000110
departmentalInfo.oktmo=01701000
departmentalInfo.paymentKind110=НС
departmentalInfo.reasonCode106=ТП
departmentalInfo.uip=0
externalId=a0000000-0000-0000-0000-000000000001
incomeTypeCode=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 { | |||
amount | number | required | Сумма платежа, |
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа, |
date | string | required | Дата составления документа, |
deliveryKind | string | optional | Вид платежа, |
departmentalInfo | DepartmentalInfo | optional | Реквизиты налогового, таможенного или иного бюджетного платежа, |
digestSignatures | array[Signature] | optional | Электронные подписи по дайджесту документа, |
externalId | string | required | Идентификатор документа, который вы присваиваете самостоятельно, |
incomeTypeCode | string | optional | Код вида дохода получателей выплаты по 229-ФЗ, |
number | string | optional | Номер документа, |
operationCode | string | required | Код операции, |
payeeAccount | string | optional | Счет получателя платежа, |
payeeBankBic | string | required | БИК получателя платежа, |
payeeBankCorrAccount | string | optional | Корсчет банка получателя платежа, |
payeeInn | string | optional | ИНН получателя платежа, |
payeeKpp | string | optional | КПП получателя платежа, |
payeeName | string | required | Полное наименование получателя платежа, |
payerAccount | string | required | Счет плательщика, |
payerBankBic | string | required | БИК банка плательщика, |
payerBankCorrAccount | string | required | Корсчет банка плательщика, |
payerInn | string | required | ИНН плательщика, |
payerKpp | string | required | КПП плательщика, |
payerName | string | required | Полное наименование плательщика, |
priority | string | required | Очередность платежа, |
purpose | string | required | Назначение платежа, |
urgencyCode | string | optional | Код срочности, |
vat | Vat | optional | Данные НДС, |
voCode | string | optional | Код вида валютной операции |
} | |||
DepartmentalInfo { | |||
uip | string | required | Уникальный идентификатор платежа, |
drawerStatus101 | string | required | Показатель статуса налогоплательщика (реквизит - 101), |
kbk | string | required | Код бюджетной классификации (реквизит - 104), |
oktmo | string | required | Код OKTMO (реквизит - 105), |
reasonCode106 | string | required | Показатель основания платежа (реквизит - 106), |
taxPeriod107 | string | required | Налоговый период / код таможенного органа (реквизит - 107), |
docNumber108 | string | required | Номер налогового документа (реквизит - 108), |
docDate109 | string | required | Дата налогового документа (реквизит - 109), |
paymentKind110 | string | optional | Тип налогового платежа (реквизит - 110) |
} | |||
Signature { | |||
base64Encoded | string | required | Значение электронной подписи (ЭП), закодированное в Base64, |
certificateUuid | string | required | Уникальный идентификатор сертификата ключа проверки электронной подписи |
} | |||
Vat { | |||
amount | number | optional | Сумма НДС, |
rate | string | optional | Ставка НДС, |
type | string | required | Способ расчета НДС |
} |
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
{
"number": "2",
"date": "2024-08-16",
"departmentalInfo":{
"uip":"0",
"drawerStatus101":"01",
"kbk":"18210102010011000110",
"oktmo":"01701000",
"reasonCode106":"ТП",
"taxPeriod107":"ГД.00.2018",
"docNumber108":"123",
"docDate109":"2017.01.01",
"paymentKind110":"1"
},
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"bankStatus": "CREATED",
"bankComment": null,
"externalId": "af0ce133-4b20-4e52-8653-ea4d5081f7bb",
"amount": "1.01",
"operationCode": "01",
"deliveryKind": "электронно",
"priority": "5",
"urgencyCode": null,
"voCode": null,
"purpose": "Оплата заказа №123. НДС нет.",
"payerName": "ООО_АВТОТЕСТ_КЛИЕНТ_ЕКС_20230913200214",
"payerInn": "8268536784",
"payerKpp": "704401351",
"payerAccount": "40702810606000001671",
"payerBankBic": "048073601",
"payerBankCorrAccount": "30101810300000000601",
"payeeName": "ИП_Автотест_Клиент_ЕКС_20231027092336",
"payeeInn": "213504669246",
"payeeKpp": "346801713",
"payeeAccount": "40802810706000000087",
"payeeBankBic": "048073601",
"payeeBankCorrAccount": "30101810300000000601",
"crucialFieldsHash": "456c6c56324ebe6b64fd160eaefb310d",
"vat": {
"type": "NO_VAT",
"rate": "0",
"amount": "0.00"
},
"incomeTypeCode": null
}
400 (Bad request)
Cause | Message | Description |
---|---|---|
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 { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
checks | array[Check] | optional | Список проверок, приведших к ошибке, |
fieldNames | array[string] | optional | Названия полей с некорректным значением (только для VALIDATION_FAULT) |
} | |||
Check { | |||
level | string | optional | Уровень результата = ['ERROR', 'WARNING'], |
message | string | optional | Сообщение, |
fields | array[string] | optional | Названия полей (при наличии связи с моделью) |
} |
403 (Forbidden)
Cause | Message | Description |
---|---|---|
ACTION_ACCESS_EXCEPTION | Операция не может быть выполнена: доступ к ресурсу запрещен | Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция PAY_DOC_RU . Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"cause": "ACTION_ACCESS_EXCEPTION",
"referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
"message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}
500 (Internal Server Error)
Cause | Message | Description |
---|---|---|
UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
503 (Service Temporarily Unavailable)
Cause | Message | Description |
---|---|---|
UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
"message": "Внутренняя ошибка сервера"
}
Получить статус платежного поручения
/fintech/api/v1/payments/{externalId}
Ресурс позволяет вам получить статус ранее сформированного черновика платежного поручения. В случае, если у Клиента отключена/истек срок соглашения услуги на формирование платежных поручений, вы все равно сможете получить статус готовых документов.
Для получения статуса необходимо отправить GET-запрос /fintech/api/v1/payments/{externalId}/state
с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатор документа (externalId) в querry-параметре запроса.
В параметре 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 | |||||
Authorization | string | string | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
Accept | string | string | ^(application/json|application/jose) | optional | Указывает на формат данных, который вы готовы принять от Банка. - Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. - Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose. |
PATH PARAMETERS | |||||
externalId | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | required | Идентификатор документа, присвоенный вами при создании документа |
GET /fintech/api/v1/payments/6a54593d-464b-4c8e-a7e2-742a05e5c241/state HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*
Responses
200 (ОК)
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
PaymentDocState { | |||
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
channelInfo | string | optional | Комментарий, специфичный для документа, полученного по данному каналу, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа |
} |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"bankStatus": "CREATED",
"bankComment": null,
"channelInfo": null,
"crucialFieldsHash": "0c78790070b8487a4d73151bdab59899"
}
400 (Bad request)
Cause | Message | Description |
---|---|---|
DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. |
VALIDATION_FAULT | Ошибка валидации | Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
ResourceFault { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
checks | array[Check] | optional | Список проверок, приведших к ошибке, |
fieldNames | array[string] | optional | Названия полей с некорректным значением (только для VALIDATION_FAULT) |
} | |||
Check { | |||
level | string | optional | Уровень результата = ['ERROR', 'WARNING'], |
message | string | optional | Сообщение, |
fields | array[string] | optional | Названия полей (при наличии связи с моделью) |
} |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"cause": "VALIDATION_FAULT",
"referenceId": "0d6a80ba-7d35-4858-8443-9a77039ad9f1",
"message": "Параметр \"externalId\" не соответствует регулярному выражению: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
"checks": [],
"fieldNames": null
}
401 (Unauthorized Error)
Cause | Message | Description |
---|---|---|
UNAUTHORIZED | accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAUTHORIZED",
"referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
"message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}
403 (Forbidden)
Cause | Message | Description |
---|---|---|
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 { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"cause": "ACTION_ACCESS_EXCEPTION",
"referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
"message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}
404 (Not found)
Cause | Message | Description |
---|---|---|
NOT_FOUND | Документ с указанным ID не найден |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"cause": "NOT_FOUND",
"referenceId": "1bd1b8b9-1bd3-4159-9909-d30536211114",
"message": "Документ с указанным ID не найден"
}
500 (Internal Server Error)
Cause | Message | Description |
---|---|---|
UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
503 (Service Temporarily Unavailable)
Cause | Message | Description |
---|---|---|
UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
"message": "Внутренняя ошибка сервера"
}
Статусы платежных поручений
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 | Исполнен | Электронный документ исполнен Банком |
Получить статус платежного поручения
/fintech/api/v1/payments/{externalId}
Ресурс позволяет вам получить статус ранее сформированного черновика платежного поручения. В случае, если у Клиента отключена/истек срок соглашения услуги на формирование платежных поручений, вы все равно сможете получить статус готовых документов.
Для получения статуса необходимо отправить GET-запрос /fintech/api/v1/payments/{externalId}/state
с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатор документа (externalId) в querry-параметре запроса.
В параметре 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 | |||||
Authorization | string | string | ^[a-zA-Z0-9]{38}$ | required | Access token пользователя, полученный через SSO. |
Accept | string | string | ^(application/json|application/jose) | optional | Указывает на формат данных, который вы готовы принять от Банка. - Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. - Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose. |
PATH PARAMETERS | |||||
externalId | string | UUID | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | required | Идентификатор документа, присвоенный вами при создании документа |
GET /fintech/api/v1/payments/6a54593d-464b-4c8e-a7e2-742a05e5c241/state HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*
Responses
200 (ОК)
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Payment { | |||
amount | number | required | Сумма платежа, |
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа, |
date | string | required | Дата составления документа, |
deliveryKind | string | optional | Вид платежа, |
departmentalInfo | DepartmentalInfo | optional | Реквизиты налогового, таможенного или иного бюджетного платежа, |
digestSignatures | array[Signature] | optional | Электронные подписи по дайджесту документа, |
externalId | string | required | Идентификатор документа, присвоенный партнером, |
incomeTypeCode | string | optional | Код вида дохода получателей выплаты по 229-ФЗ, |
number | string | optional | Номер документа, |
operationCode | string | required | Код операции, |
payeeAccount | string | optional | Счет получателя платежа, |
payeeBankBic | string | required | БИК получателя платежа, |
payeeBankCorrAccount | string | optional | Корсчет банка получателя платежа, |
payeeInn | string | optional | ИНН получателя платежа, |
payeeKpp | string | optional | КПП получателя платежа, |
payeeName | string | required | Полное наименование получателя платежа, |
payerAccount | string | required | Счет плательщика, |
payerBankBic | string | required | БИК банка плательщика, |
payerBankCorrAccount | string | required | Корсчет банка плательщика, |
payerInn | string | required | ИНН плательщика, |
payerKpp | string | optional | КПП плательщика, |
payerName | string | required | Полное наименование плательщика, |
priority | string | required | Очередность платежа, |
purpose | string | required | Назначение платежа, |
urgencyCode | string | optional | Код срочности, |
vat | vat | optional | Данные НДС, |
voCode | string | optional | Код вида валютной операции |
} | |||
DepartmentalInfo { | |||
uip | string | required | Уникальный идентификатор платежа, |
drawerStatus101 | string | required | Показатель статуса налогоплательщика (реквизит - 101), |
kbk | string | required | Код бюджетной классификации (реквизит - 104), |
oktmo | string | required | Код OKTMO (реквизит - 105), |
reasonCode106 | string | required | Показатель основания платежа (реквизит - 106), |
taxPeriod107 | string | required | Налоговый период / код таможенного органа (реквизит - 107), |
docNumber108 | string | required | Номер налогового документа (реквизит - 108), |
docDate109 | string | required | Дата налогового документа (реквизит - 109), |
paymentKind110 | string | optional | Тип налогового платежа (реквизит - 110) |
} | |||
Signature { | |||
base64Encoded | string | required | Значение электронной подписи, закодированное в Base64, |
certificateUuid | string | required | Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID), |
} | |||
Vat { | |||
amount | number | optional | Сумма НДС, |
rate | string | optional | Ставка НДС, |
type | string | required | Способ расчета НДС |
} |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"number": "1",
"date": "2023-11-15",
"digestSignatures": [],
"bankStatus": "CREATED",
"bankComment": null,
"externalId": "6a54593d-464b-4c8e-a7e2-742a05e5c241",
"amount": "100.00",
"operationCode": "01",
"deliveryKind": "электронно",
"priority": "5",
"urgencyCode": "NORMAL",
"voCode": null,
"purpose": "Оплата заказа №123. НДС 20%",
"departmentalInfo": null,
"payerName": "ООО_Автотест_Клиент_ЕКС_20231027092414",
"payerInn": "6376615662",
"payerKpp": "702701625",
"payerAccount": "40702810506000002149",
"payerBankBic": "048073601",
"payerBankCorrAccount": "30101810300000000601",
"payeeName": "ТЕСТ9036",
"payeeInn": "7379190522",
"payeeKpp": "683801910",
"payeeAccount": "40702810006000001792",
"payeeBankBic": "048073601",
"payeeBankCorrAccount": "30101810300000000601",
"crucialFieldsHash": null,
"vat": {
"type": "INCLUDED",
"rate": "20",
"amount": "20.00"
},
"incomeTypeCode": null
}
400 (Bad request)
Cause | Message | Description |
---|---|---|
DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. |
VALIDATION_FAULT | Ошибка валидации | Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
ResourceFault { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
checks | array[Check] | optional | Список проверок, приведших к ошибке, |
fieldNames | array[string] | optional | Названия полей с некорректным значением (только для VALIDATION_FAULT) |
} | |||
Check { | |||
level | string | optional | Уровень результата = ['ERROR', 'WARNING'], |
message | string | optional | Сообщение, |
fields | array[string] | optional | Названия полей (при наличии связи с моделью) |
} |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"cause": "VALIDATION_FAULT",
"referenceId": "0d6a80ba-7d35-4858-8443-9a77039ad9f1",
"message": "Параметр \"externalId\" не соответствует регулярному выражению: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
"checks": [],
"fieldNames": null
}
401 (Unauthorized Error)
Cause | Message | Description |
---|---|---|
UNAUTHORIZED | accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAUTHORIZED",
"referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
"message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}
403 (Forbidden)
Cause | Message | Description |
---|---|---|
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 { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"cause": "ACTION_ACCESS_EXCEPTION",
"referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
"message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}
404 (Not found)
Cause | Message | Description |
---|---|---|
NOT_FOUND | Документ с указанным ID не найден |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"cause": "NOT_FOUND",
"referenceId": "1bd1b8b9-1bd3-4159-9909-d30536211114",
"message": "Документ с указанным ID не найден"
}
500 (Internal Server Error)
Cause | Message | Description |
---|---|---|
UNKNOWN_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"cause": "UNKNOWN_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
"message": "Внутренняя ошибка сервера"
}
503 (Service Temporarily Unavailable)
Cause | Message | Description |
---|---|---|
UNAVAILABLE_RESOURCE_EXCEPTION | Внутренняя ошибка сервера | Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка. |
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Notice { | |||
cause | string | optional | Причина или основание сообщения, |
referenceId | string | optional | Уникальный идентификатор ошибки (UUID), |
message | string | optional | Сообщение, |
} |
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
{
"cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
"referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
"message": "Внутренняя ошибка сервера"
}
Дополнительная информация
Назначение платежа
Назначение должно раскрывать экономический смысл платежа.
- Сведения должны быть лаконичными — у поля есть ограничения по знакам 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 рубля
.