Сервис «Моментальные платежи»
Информация о сервисе
Моментальные платежи – это сервис для организации расчетов между юридическими лицами (ЮЛ) и индивидуальными предпринимателями (ИП), который позволяет формировать и отслеживать статус платежного документа в СберБизнес плательщика.
Ядро механизма сервиса составляют платежные поручения, которые используются в качестве платежных документов для расчетов между компаниями.
Платежное поручение
Платежное поручение – это документ, который используется для указания банку перевести определенную сумму денег с одного счета на другой. Обычно это делается, когда компания хочет произвести оплату за товары или услуги, перевести деньги индивидуальному предпринимателю или юридическому лицу.
Платежные поручения используются широким кругом лиц, включая индивидуальных предпринимателей, малый и средний бизнес, крупные корпорации и даже государственные учреждения. Их используют, когда нужно сделать перевод, который требует предварительного уведомления или планирования (например, оплата аренды, коммунальных услуг или выплата заработной платы).
До начала разработки интеграции с сервисом потребуется:
- Заключить договор с Банком на использование сервиса "Моментальные платежи".
- Завершить интеграцию со СберБизнес ID.
Без сервиса СберБизнес ID настроить работу "Моментальные платежи" невозможно.
Схема работы сервиса
- Графическое описание
- Текстовое описание
Шаг | Что делаем | Подробности |
---|---|---|
1 | Предложите Клиенту авторизоваться через СберБизнес ID | Шаг реализуется с помощью СберБизнес ID - в рамках процесса авторизации через СберБизнес ID вы получаете access_token клиента и, при необходимости, дополнительную информацию о Клиенте. Подробно о подключении сервиса СберБизнес ID рассказали в соответствующем разделе документации. |
2 | Сформируйте черновик платежного поручения | С помощью одного из предложенных ниже POST-запросов и access_token пользователя Клиента вы создатите черновик платежного поручения в СберБизнес Клиента. Для создания черновика платежного поручения выберете ресурс, который подходит под ваши задачи: /v1/payments/from-invoice — для получения денежных средств на счет вашей компании в Сбербанке./v1/payments/from-invoice-any — для организации переводов, где отправитель — любая компания со счетом в Сбербанке, а получатель — любая компания со счетом в любом банке./v1/payments/from-invoice-budget — для разработки функциональности по оплате налоговых, таможенных и других бюджетных платежей. |
3 | Перенаправьте клиента в сервис оплаты | С использованием идентификатора созданного черновика платежного поручения из шага №2 вы формируете ссылку для оплаты и перенаправляете по ней пользователя Клиента. Перейдя по ссылке в сервис оплаты, пользователь пройдет аутентификацию, выберет счет списания и подпишет черновик платежного поручения для исполнения Банком. Ссылка переадресации выглядит следующим образом: {контур Банка}/ic/dcb/index.html#/payment-creator/{externalid}?backUrl={backUrl} Дополнительная информация о формировании ссылки. |
4 | Получите статус платежного поручения | С помощью ресурса /v1/payments/{externalId}/state вы сможете разработать механизм проверки статуса оплаты и реакцию Платформы на каждый из них.В этой части страницы указали все статусы платежного поручения и их описание. |
5 | Проверьте корректность платежа | С помощью ресурса /v1/payments/{externalId} вы сможете получить все параметры ранее созданного платежного поручения. Эту информацию можно использовать, например, в механизме проверки корректности платежа. |
Клиентский путь
Глазами Пользователя
Шаг | Действия | Скрин |
---|---|---|
1 | Пользователь выбрал интересующий продукт и перешел к оплате. Вы предлагаете авторизоваться через СберБизнес ID. | |
2 | Нажал на "Войти по СберБизнес ID" и попал на станицу аутентификации. | |
3 | После успешной аутентификации СберБизнес ID предлагает подписать Согласие. | |
4 | Платформа создала платежное поручение и переадресовала Пользователя на него. | |
5 | Пользователь выбрал счет списания и подписал платежное поручение. |
Варианты реализации
В рамках Платформы вы самостоятельно разрабатываете ролевую модель и настраиваете права доступа к функциональности.
Ниже, в качестве примера, приведена диаграмма вариантов использования:
- Подойдет для получения денежных средств на счет вашей компании в Сбербанке
Оплата на счет вашей компании в Сбербанке
Шаги
- Получить access_token
- Сформировать черновик платежного поручения
- Подписать черновик платежного поручения
- Проверить статус оплаты
- Проверить корректность платежа
Участники usecase
- Клиент - представитель ЮЛ/ИП, который от лица своей компании приобретает услуги или товары вашей компании;
- Платформа - любой web-ресурс (интернет-магазин, мобильное приложение и т.д.), который вы используете в рамках клиентского пути Клиентов;
- Банк - в контексте данного usecase представляет из себя ресурсы и ресурсы Sber API, к которым обращается Платформа, и СберБизнес, на который переадресовывают Клиента для проведения оплаты.
Предусловия
- Клиент имеет пользовательский профиль в СберБизнес своей компании с правом подписи;
- Клиент находится на Платформе.
Постусловия
- Проведена оплата за товары/услуги на счет вашей компании.
Используемые ресурсы
№ | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
---|---|---|---|---|---|
1 | /v2/oauth/authorize | Получение кода авторизации | openid | 1. Получить access_token | |
2 | /v2/oauth/token | Получение токена доступа | openid | 1. Получить access_token | |
3 | /v2/oauth/user-info | Получение информации | openid | 1. Получить access_token | |
4 | /v1/payments/from-invoice | Создать черновик платежного поручения (отправка на свой счет в Сбербанке) | PAY_DOC_RU_INVOICE | 2. Сформировать черновик платежного поручения | |
5 | /v1/payments/{externalId}/state | Получить статус платежного поручения | PAY_DOC_RU_INVOICE | 4. Проверить статус оплаты | |
6 | /v1/payments/{externalId} | Получить атрибуты платежного поручения | PAY_DOC_RU_INVOICE | 5. Проверить корректность платежа |
- Подойдет для организации переводов, где отправитель — любая компания со счетом в Сбербанке, а получатель — любая компания со счетом в любом банке.
Расчеты B2B
Шаги
- Получить access_token
- Сформировать черновик платежного поручения
- Подписать черновик платежного поручения
- Проверить статус оплаты
- Проверить корректность платежа
Участники usecase
- Клиент - представитель ЮЛ/ИП, который от лица своей компании приобретает услуги или товары (вашей или другой) компании;
- Платформа - любой web-ресурс (интернет-магазин, мобильное приложение и т.д.), который вы используете в рамках клиентского пути Клиентов;
- Банк - в контексте данного usecase представляет из себя ресурсы и ресурсы Sber API, к которым обращается Платформа, и СберБизнес, на который переадресовывают Клиента для проведения оплаты.
Предусловия
- Клиент имеет пользовательский профиль в СберБизнес своей компании с правом подписи;
- Клиент находится на Платформе.
Постусловия
- Проведена оплата за товары/услуги на счет (вашей или другой) компании.
Используемые ресурсы
№ | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
---|---|---|---|---|---|
1 | /v2/oauth/authorize | Получение кода авторизации | openid | 1. Получить access_token | |
2 | /v2/oauth/token | Получение токена доступа | openid | 1. Получить access_token | |
3 | /v2/oauth/user-info | Получение информации | openid | 1. Получить access_token | |
4 | /v1/payments/from-invoice-any | Создать черновик платежного поручения (отправка в любой банк) | PAY_DOC_RU_INVOICE_ANY | 2. Сформировать черновик платежного поручения | |
5 | /v1/payments/{externalId}/state | Получить статус платежного поручения | PAY_DOC_RU_INVOICE_ANY | 4. Проверить статус оплаты | |
6 | /v1/payments/{externalId} | Получить атрибуты платежного поручения | PAY_DOC_RU_INVOICE_ANY | 5. Проверить корректность платежа |
- Подойдет для разработки функциональности по оплате налоговых, таможенных и других бюджетных платежей.
Платежи в бюджет
Шаги
- Получить реквизиты оплаты
- Получить access_token
- Сформировать черновик платежного поручения
- Подписать черновик платежного поручения
- Проверить статус оплаты
- Проверить корректность платежа
Участники usecase
- Клиент - представитель ЮЛ/ИП, который от лица своей компании хочет сделать оплату в пользу бюджетной организации через Плафторму;
- Платформа - любой web-ресурс (интернет-магазин, мобильное приложение и т.д.), который вы используете в рамках клиентского пути Клиентов;
- Банк - в контексте данного usecase представляет из себя ресурсы и ресурсы Sber API, к которым обращается Платформа, и СберБизнес, на который переадресовывают Клиента для проведения оплаты.
Предусловия
- Клиент имеет пользовательский профиль в СберБизнес своей компании с правом подписи;
- Клиент находится на Платформе.
Постусловия
- Проведена оплата в пользу бюджетной компании.
Используемые ресурсы
№ | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
---|---|---|---|---|---|
1 | /v2/oauth/authorize | Получение кода авторизации | openid | 2. Получить access_token | |
2 | /v2/oauth/token | Получение токена доступа | openid | 2. Получить access_token | |
3 | /v2/oauth/user-info | Получение информации | openid | 2. Получить access_token | |
4 | /v1/payments/from-invoice-any | Создать черновик платежного поручения (отправка в бюджет) | PAY_DOC_RU_INVOICE_BUDGET | 3. Сформировать черновик платежного поручения | |
5 | /v1/payments/{externalId}/state | Получить статус платежного поручения | PAY_DOC_RU_INVOICE_BUDGET | 5. Проверить статус оплаты | |
6 | /v1/payments/{externalId} | Получить атрибуты платежного поручения | PAY_DOC_RU_INVOICE_BUDGET | 6. Проверить корректность платежа |
Переадресация на платежное поручение
Чтобы Банк начал обработку платежного поручения, платежное поручение должно быть подписано. В клиентском пути сервиса платежное поручение формируется в клиентской части СберБизнес Клиента, поэтому и подписывать платежное поручение должен Клиент.
Для реализации бесшовного перехода в клиентскую часть СберБизнес необходима переадресация Клиента. Перейдя по ссылке в сервис оплаты, клиент пройдет аутентификацию, выберет счет списания и подпишет черновик платежного поручения для его исполнения Банком.
- Модель ссылки
- Пример
Ссылка переадресации выглядит следующим образом:
{контур Банка}/ic/dcb/index.html#/payment-creator/{externalid}?backUrl={backUrl}
Переменная | Описание | Дополнительная информация |
---|---|---|
{контур Банка} | адрес Банка, на который делается запрос для открытия страницы сервиса оплаты | Для корректного выбора контура Банка потребуется определить тип криптопрофиля пользователя Клиента. В рамках запроса /v1/oauth/user-info вы получаете данные по Клиенту, в том числе атрибут userCryptoType.Атрибут позволяет определить криптопрофиль пользователя - SMS (СМС) или Token (электронный ключ (токен)). - Тестовый контур https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443 - Промышленный контур СМС-пользователь https://sbi.sberbank.ru:9443 - Промышленный контур Токен-пользователь http://localhost:28016 |
{externalid} | уникальный идентификатор платежного документа | Данный идентификатор присваивает ваша Платформа на шаге создания черновика платежного поручения |
{backUrl} | страница возврата, на которую Банк вернет пользователя Клиента после успешного подписания черновика платежного поручения | - backUrl нужно закодировать URLEncode; - Если не указать backUrl в ссылке, пользователи не смогут после подписания платежного поручения вернуться на Платформу; - Если backUrl будет отличаться от адреса вашей платформы, который указали при регистрации в Банке, то при возврате клиента на backUrl он будет видеть ошибку. |
https://sbi.sberbank.ru:9443/ic/dcb/index.html#/payment-creator/d4fbfe27-ee37-4451-b224-8113a06c44a3?backUrl=https://www.example.ru/
Создать черновик платежного поручения (отправка на свой счет в Сбербанке)
/v1/payments/from-invoice
Ресурс позволяет вам создавать черновики платежных поручений с фиксированным сроком действия, в которых отсутствует возможность изменить сумму оплаты и реквизиты получателя. Получение денежных средств с помощью данного ресурса возможно только на расчетный счет в Сбербанке, который принадлежит вашей организации.
Для создания черновика платежного поручения необходимо отправить POST-запрос /v1/payments/from-invoice
с токеном доступа (access_token) пользователя в параметре Authorization заголовка и реквизитами счета в теле запросе.
В параметре scope ссылки авторизации пользователя должен быть указан сервис PAY_DOC_RU_INVOICE
для получения доступа к этому ресурсу.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443/fintech/api
- Промышленный контур
https://fintech.sberbank.ru:9443/fintech/api
Request
/v1/payments/from-invoice
- Модель
- Пример
Наименование | Тип | Формат | Regexp | Обязательность | Описание |
---|---|---|---|---|---|
HEADER | |||||
Authorization | string | string | ^([a-zA-Z0-9]){38}$ | required | Access token пользователя, полученный через SSO. |
BODY | |||||
Invoice { | |||||
amount | number | float | ^[0-9]+(.[0-9]+)?$ | required | Сумма платежа, |
date | string | ISO 8601 YYYY-MM-DD | ^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$ | required | Дата составления документа, |
deliveryKind | string | string | ^(электронно|срочно|0)$ | optional | Вид платежа. Если не заполнено или 0, то будет присвоено значение "электронно", |
expirationDate | string | ISO 8601 YYYY-MM-DD | ^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$ | optional | Дата истечения заказа (платеж должен быть подтвержден клиентом), |
externalId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | required | Идентификатор документа, присвоенный партнером, |
linkedDocs | Array[LinkedDoc] | object | optional | Связанные документы, | |
operationCode | string | string | ^01$ | optional | Код операции, |
orderNumber | string | string | ^[0-9]$ | optional | Номер заказа, |
payeeAccount | string | string | ^[0-9]{20}$ | required | Счет получателя платежа, |
payeeOrgIdHash | string | string | ^[0-9a-f]{64}$ | optional | Идентификатор получателя платежа, |
paymentNumber | string | string | ^[0-9]{1,6}$ | optional | Номер платежного поручения. Если Клиент не ведет в своей учетной системе нумерацию платежных поручений, созданных на основании выставленных счетов, то атрибут можно не передавать, он будет присвоен автоматически, |
priority | string | string | ^[4-5]{1}$ | optional | Очередность платежа, |
purpose | string | string | ^[a-zA-Z0-9._ -]{1,210}$ | required | Назначение платежа. Рекомендации по заполнению, |
urgencyCode | string | string | ^(INTERTAL|INTERNAL_NOTIF|OFFHOUR|BESP|NORMAL)$ | optional | Код срочности. INTERNAL - срочный INTERNAL_NOTIF - срочный платеж с уведомлением OFFHOUR - неотложный BESP - банковские электронные срочные платежи NORMAL - срочность не указана, |
vat | Array[Vat] | object | required | Данные НДС | |
} | |||||
LinkedDoc [ | |||||
{ | |||||
docExtId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | optional | Идентификатор документа (заявления на страхование экспортного контракта) во внешней системе (UUID), к которому необходимо привязать платежное поручение, |
type | string | string | ^(ExportContractInsure)$ | optional | Тип связанного документа (доступное значение для заполнения - exportContractInsure), с которым необходимо связать платежное поручение |
} | |||||
] | |||||
Vat { | |||||
amount | number | float | ^[0-9]+(.[0-9]+)?$ | 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/from-invoice HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
{
"amount": 100.00,
"date": "2023-11-14",
"deliveryKind": "электронно",
"expirationDate": "2023-11-30",
"externalId": "534bb614-5d3b-4f29-a667-c8dd51be9e7e",
"operationCode": "01",
"orderNumber": "123",
"payeeAccount": "40702810006000001792",
"paymentNumber": "1",
"priority": "5",
"purpose": "Оплата заказа №123. НДС 20%",
"urgencyCode": "NORMAL",
"vat": {
"type": "INCLUDED",
"amount": 20.00,
"rate": "20"
}
}
Responses
201 (Created)
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Payment { | |||
amount | number | required | Сумма платежа, |
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа, |
date | string | required | Дата составления документа, |
deliveryKind | string | optional | Вид платежа, |
departmentalInfo | Array[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 201 Created
Content-Type: application/json;charset=UTF-8
{
"number": "1",
"date": "2023-11-14",
"digestSignatures": [],
"bankStatus": "CREATED",
"bankComment": null,
"externalId": "534bb614-5d3b-4f29-a667-c8dd51be9e7e",
"amount": "100.00",
"operationCode": "01",
"deliveryKind": "электронно",
"priority": "5",
"urgencyCode": "NORMAL",
"voCode": null,
"purpose": "Оплата заказа №123. НДС 20%",
"departmentalInfo": null,
"payerName": "ИП_Автотест_Клиент_ЕКС_20231027092336",
"payerInn": "213504669246",
"payerKpp": "346801713",
"payerAccount": "40802810706000000087",
"payerBankBic": "048073601",
"payerBankCorrAccount": "30101810300000000601",
"payeeName": "ТЕСТ9036",
"payeeInn": "7379190522",
"payeeKpp": "683801910",
"payeeAccount": "40702810006000001792",
"payeeBankBic": "048073601",
"payeeBankCorrAccount": "30101810300000000601",
"crucialFieldsHash": "0c78790070b8487a4d73151bdab59899",
"vat": {
"type": "INCLUDED",
"rate": "20",
"amount": "20.00"
},
"incomeTypeCode": null
}
400 (Bad request)
Cause | Message | Description |
---|---|---|
DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. |
WORKFLOW_FAULT | Не найдена организация получателя по payeeOrgIdHash: <значение payeeOrgIdHash> | Проверьте корректность поля payeeOrgIdHash. Также можно в повторном запросе не указывать данное поле - оно не обязательное. |
Невозможно идентифицировать организацию плательщика | Проверьте корректность указанных реквизитов плательщика. | |
Документ с таким externalId уже существует в системе | Используется externalId, который уже есть в системе (дубль). Сгенерируйте новый externalId и повторите запрос. | |
Отсутствует доступный открытый рублевый расчетный счет у организации плательщика | Плательщику требуется открыть рублевый расчетный счет в Сбербанке. | |
Неизвестный счет получателя: <счет получателя платежа> | Проверьте корректность указанного счета в атрибуте payeeAccount. Счет должен принадлежать вашей организации. | |
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": "145ac7ed-9c20-4a75-8135-8a978d403836",
"message": "Объект Invoice не соответствует модели",
"checks": [
{
"level": "ERROR",
"message": "должно соответствовать \"^(электронно|срочно|0)$\"",
"fields": [
"deliveryKind"
]
}
],
"fieldNames": [
"deliveryKind"
]
}
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_INVOICE . Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. |
Вы использовали access_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": "Внутренняя ошибка сервера"
}
Создать черновик платежного поручения (отправка в любой банк)
/v1/payments/from-invoice-any
Ресурс позволяет вам создавать черновики платежных поручений по свободным реквизитам. Получение денежных средств возможно на счета сторонних банков. В качестве получателя денежных средств может выступать любая организация.
Для создания черновика платежного поручения необходимо отправить POST-запрос /v1/payments/from-invoice-any
с токеном доступа (access_token) пользователя в параметре Authorization заголовка и реквизитами счета в теле запросе.
В параметре scope ссылки авторизации пользователя должен быть указан сервис PAY_DOC_RU_INVOICE_ANY
для получения доступа к этому ресурсу.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443/fintech/api
- Промышленный контур
https://fintech.sberbank.ru:9443/fintech/api
Request
/v1/payments/from-invoice-any
- Модель
- Пример
Наименование | Тип | Формат | Regexp | Обязательность | Описание |
---|---|---|---|---|---|
HEADER | |||||
Authorization | string | string | ^([a-zA-Z0-9]){38}$ | required | Access token пользователя, полученный через SSO. |
BODY | |||||
Invoice { | |||||
amount | number | float | ^[0-9]+(.[0-9]+)?$ | required | Сумма платежа, |
creditContractNumber | string | string | ^[0-9]$ | optional | Номер кредитного договора, |
date | string | ISO 8601 YYYY-MM-DD | ^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$ | required | Дата составления документа, |
deliveryKind | string | string | ^(электронно|срочно|0)$ | optional | Вид платежа. Если не заполнено или 0, то будет присвоено значение "электронно", |
expirationDate | string | ISO 8601 YYYY-MM-DD | ^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$ | optional | Дата истечения заказа (платеж должен быть подтвержден клиентом), |
externalId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | required | Идентификатор документа, присвоенный партнером, |
isPaidByCredit | boolean | boolean | ^(true|false)$ | optional | Признак того, что платежное поручение будет оплачено за счет кредитных средств, |
linkedDocs | Array[LinkedDoc] | object | optional | Связанные документы, | |
operationCode | string | string | ^01$ | optional | Код операции, |
orderNumber | string | string | ^[0-9]$ | optional | Номер заказа, |
payeeAccount | string | string | ^[0-9]{20}$ | required | Счет получателя платежа, |
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)$ | required | ИНН получателя платежа, |
payeeKpp | string | string | ^([0-9]{9}|0)$ | optional | КПП получателя платежа, |
payeeName | string | string | ^[0-9a-zA-Zа-яА-ЯеЁ \t]+$ | required | Наименование получателя платежа, |
paymentNumber | string | string | ^[0-9]{1,6}$ | optional | Номер платежного поручения. Если Клиент не ведет в своей учетной системе нумерацию платежных поручений, созданных на основании выставленных счетов, то атрибут можно не передавать, он будет присвоен автоматически, |
priority | string | string | ^[4-5]{1}$ | optional | Очередность платежа, |
purpose | string | string | ^[a-zA-Z0-9._ -]{1,210}$ | required | . Рекомендации по заполнению, |
urgencyCode | string | string | ^(INTERTAL|INTERNAL_NOTIF|OFFHOUR|BESP|NORMAL)$ | optional | Код срочности. INTERNAL - срочный INTERNAL_NOTIF - срочный платеж с уведомлением OFFHOUR - неотложный BESP - банковские электронные срочные платежи NORMAL - срочность не указана, |
vat | Array[Vat] | object | required | Данные НДС | |
} | |||||
LinkedDoc [ | |||||
{ | |||||
docExtId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | optional | Идентификатор документа (заявления на страхование экспортного контракта) во внешней системе (UUID), к которому необходимо привязать платежное поручение, |
type | string | string | ^(ExportContractInsure)$ | optional | Тип связанного документа (доступное значение для заполнения - exportContractInsure), с которым необходимо связать платежное поручение |
} | |||||
] | |||||
Vat { | |||||
amount | number | float | ^[0-9]+(.[0-9]+)?$ | 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/from-invoice-any HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
{
"amount": 100.00,
"date": "2023-11-14",
"deliveryKind": "электронно",
"expirationDate": "2023-11-30",
"externalId": "691496e5-75a3-43cf-9908-f3e3c073e657",
"operationCode": "01",
"orderNumber": "123",
"payeeAccount": "40702810006000001792",
"payeeBankBic": "044525225",
"payeeInn": "7379190522",
"payeeKpp": "0",
"payeeName": "ТЕСТ9036",
"paymentNumber": "1",
"priority": "5",
"purpose": "Оплата заказа №123. НДС 20%",
"urgencyCode": "NORMAL",
"vat": {
"type": "INCLUDED",
"amount": 20.00,
"rate": "20"
}
}
Responses
201 (Created)
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Payment { | |||
amount | number | required | Сумма платежа, |
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа, |
date | string | required | Дата составления документа, |
deliveryKind | string | optional | Вид платежа, |
departmentalInfo | Array[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 201 Created
Content-Type: application/json;charset=UTF-8
{
"number": "1",
"date": "2023-11-14",
"digestSignatures": [],
"bankStatus": "CREATED",
"bankComment": null,
"externalId": "691496e5-75a3-43cf-9908-f3e3c073e657",
"amount": "100.00",
"operationCode": "01",
"deliveryKind": "электронно",
"priority": "5",
"urgencyCode": "NORMAL",
"voCode": null,
"purpose": "Оплата заказа №123. НДС 20%",
"departmentalInfo": null,
"payerName": "ИП_Автотест_Клиент_ЕКС_20231027092336",
"payerInn": "213504669246",
"payerKpp": "346801713",
"payerAccount": "40802810706000000087",
"payerBankBic": "048073601",
"payerBankCorrAccount": "30101810300000000601",
"payeeName": "ТЕСТ9036",
"payeeInn": "7379190522",
"payeeKpp": "0",
"payeeAccount": "40702810006000001792",
"payeeBankBic": "044525225",
"payeeBankCorrAccount": null,
"crucialFieldsHash": "e9571e84cd51543c9ad44c20f4e03185",
"vat": {
"type": "INCLUDED",
"rate": "20",
"amount": "20.00"
},
"incomeTypeCode": null
}
400 (Bad request)
Cause | Message | Description |
---|---|---|
DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос. |
WORKFLOW_FAULT | Невозможно идентифицировать организацию плательщика | Проверьте корректность указанных реквизитов плательщика. |
Невозможно идентифицировать банк получателя по указанным номеру БИК и корреспондентскому счету | Проверьте корректность указанных реквизитов получателя платежа - атрибуты payeeBankBic и payeeBankCorrAccount | |
Документ с таким externalId уже существует в системе | Используется externalId, который уже есть в системе (дубль). Сгенерируйте новый externalId и повторите запрос. | |
Отсутствует доступный открытый рублевый расчетный счет у организации плательщика | Плательщику требуется открыть рублевый расчетный счет в Сбербанке. | |
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": "545f2aa0-0a57-4351-a311-db6962159008",
"message": "Объект InvoiceAny не соответствует модели",
"checks": [
{
"level": "ERROR",
"message": "не должно равняться null",
"fields": [
"payeeInn"
]
},
{
"level": "ERROR",
"message": "не должно равняться null",
"fields": [
"payeeBankBic"
]
}
],
"fieldNames": [
"payeeBankBic",
"payeeInn"
]
}
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_INVOICE_ANY . Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. |
Вы использовали access_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": "Внутренняя ошибка сервера"
}
Создать черновик платежного поручения (отправка в бюджет)
/v1/payments/from-invoice-budget
Ресурс позволяет вам создавать черновики платежных поручений в адрес бюджетных организаций со счетом в любом банке для оплаты налоговых, таможенных и других бюджетных платежей.
Для создания черновика платежного поручения необходимо отправить POST-запрос /v1/payments/from-invoice-budget
с токеном доступа (access_token) пользователя в параметре Authorization заголовка и реквизитами счета в теле запросе.
В параметре scope ссылки авторизации пользователя должен быть указан сервис PAY_DOC_RU_INVOICE_BUDGET
для получения доступа к этому ресурсу.
Для обращения к ресурсу необходимо отправлять запрос на:
- Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443/fintech/api
- Промышленный контур
https://fintech.sberbank.ru:9443/fintech/api
Request
/v1/payments/from-invoice-budget
- Модель
- Пример
Наименование | Тип | Формат | Regexp | Обязательность | Описание |
---|---|---|---|---|---|
HEADER | |||||
Authorization | string | string | ^([a-zA-Z0-9]){38}$ | required | Access token пользователя, полученный через SSO. |
BODY | |||||
Invoice { | |||||
amount | number | float | ^[0-9]+(.[0-9]+)?$ | required | Сумма платежа, |
date | string | ISO 8601 YYYY-MM-DD | ^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$ | required | Дата составления документа, |
deliveryKind | string | string | ^(электронно|срочно|0)$ | optional | Вид платежа. Если не заполнено или 0, то будет присвоено значение "электронно", |
departmentalInfo | Array[DepartmentalInfo] | object | required | Реквизиты налогового, таможенного или иного | |
бюджетного платежа, | |||||
externalId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | required | Идентификатор документа, присвоенный партнером, |
linkedDocs | Array[LinkedDoc] | object | optional | Связанные документы, | |
operationCode | string | string | ^01$ | optional | Код операции, |
payeeAccount | string | string | ^[0-9]{20}$ | required | Счет получателя платежа, |
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)$ | required | ИНН получателя платежа, |
payeeKpp | string | string | ^([0-9]{9}|0)$ | optional | КПП получателя платежа, |
payeeName | string | string | ^[0-9a-zA-Zа-яА-ЯеЁ \t]+$ | required | Наименование получателя платежа, |
paymentNumber | string | string | ^[0-9]{1,6}$ | optional | Номер платежного поручения. Если Клиент не ведет в своей учетной системе нумерацию платежных поручений, созданных на основании выставленных счетов, то атрибут можно не передавать, он будет присвоен автоматически, |
priority | string | string | ^[4-5]{1}$ | optional | Очередность платежа, |
purpose | string | string | ^[a-zA-Z0-9._ -]{1,210}$ | required | Назначение платежа. Рекомендации по заполнению, |
urgencyCode | string | string | ^(INTERTAL|INTERNAL_NOTIF|OFFHOUR|BESP|NORMAL)$ | optional | Код срочности. INTERNAL - срочный INTERNAL_NOTIF - срочный платеж с уведомлением OFFHOUR - неотложный BESP - банковские электронные срочные платежи NORMAL - срочность не указана, |
vat | Array[Vat] | object | required | Данные НДС | |
} | |||||
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) |
} | |||||
LinkedDoc [ | |||||
{ | |||||
docExtId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | optional | Идентификатор документа (заявления на страхование экспортного контракта) во внешней системе (UUID), к которому необходимо привязать платежное поручение, |
type | string | string | ^(ExportContractInsure)$ | optional | Тип связанного документа (доступное значение для заполнения - exportContractInsure), с которым необходимо связать платежное поручение |
} | |||||
] | |||||
Vat { | |||||
amount | number | float | ^[0-9]+(.[0-9]+)?$ | 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/from-invoice-budget HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
{
"amount": 64.00,
"date": "2023-11-14",
"deliveryKind": "электронно",
"externalId": "49441d51-222c-4763-ac14-3bb758d94f4c",
"number": "10",
"operationCode": "01",
"payeeAccount": "40101810800000010041",
"payeeBankBic": "044525000",
"payeeKpp": "771201001",
"payeeInn": "7713034630",
"payeeName": "11 ГУ БАНКА РОССИИ ПО ЦФО Г. Москва 35",
"payerAccount": "40702810538000001230",
"payerBankBic": "044525225",
"payerBankCorrAccount": "30101810400000000225",
"payerInn": "7785961231",
"payerKpp": "124784444",
"payerName": "ООО Тестовая",
"priority": "5",
"purpose": "Оплата счета 1 от 14.11.2023",
"urgencyCode": "NORMAL",
"vat": {
"amount": 0.00,
"rate": "0",
"type": "NO_VAT"
},
"departmentalInfo": {
"docDate109": "0",
"docNumber108": "123",
"drawerStatus101": "01",
"kbk": "00000000000000000110",
"oktmo": "32321312",
"reasonCode106": "ПК",
"taxPeriod107": "12.01.2022",
"uip": "0"
}
}
Responses
201 (Created)
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Payment { | |||
amount | number | required | Сумма платежа, |
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа, |
date | string | required | Дата составления документа, |
deliveryKind | string | optional | Вид платежа, |
departmentalInfo | Array[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 201 Created
Content-Type: application/json;charset=UTF-8
{
"number": "4",
"date": "2023-11-14",
"digestSignatures": [],
"bankStatus": "CREATED",
"bankComment": null,
"externalId":"49441d51-222c-4763-ac14-3bb758d94a4d",
"amount": 64.00,
"operationCode": "01",
"deliveryKind": "электронно",
"priority": "5",
"urgencyCode": "NORMAL",
"voCode": null,
"purpose": "Оплата счета 1 от 14.11.2023",
"departmentalInfo": {
"uip": "0",
"drawerStatus101": "01",
"kbk": "00000000000000000110",
"oktmo": "32321312",
"reasonCode106": "ПК",
"taxPeriod107": "12.09.2023",
"docNumber108": "123",
"docDate109": "0",
"paymentKind110": null
},
"payerName": "ООО_Автотест_Клиент_ЕКС_20231027092414",
"payerInn": "6376615662",
"payerKpp": "124784444",
"payerAccount": "40702810506000002149",
"payerBankBic": "048073601",
"payerBankCorrAccount": "30101810300000000601",
"payeeName": "11 ГУ БАНКА РОССИИ ПО ЦФО Г. Москва 35",
"payeeInn": "7713034630",
"payeeKpp": "771201001",
"payeeAccount": "40101810800000010041",
"payeeBankBic": "044525000",
"payeeBankCorrAccount": null,
"crucialFieldsHash": "a82a6f43eecd8b6c439255f8a83e85dc",
"vat": {
"type": "MANUAL",
"rate": "10",
"amount": 0.00
},
"incomeTypeCode":null
}
400 (Bad request)
Cause | Message | Description |
---|---|---|
DESERIALIZATION_FAULT | Неверный формат запроса | Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос. |
WORKFLOW_FAULT | Невозможно идентифицировать организацию плательщика | Проверьте корректность указанных реквизитов плательщика. |
Невозможно идентифицировать банк получателя по указанным номеру БИК и корреспондентскому счету | Проверьте корректность указанных реквизитов получателя платежа - атрибуты payeeBankBic и payeeBankCorrAccount | |
Документ с таким externalId уже существует в системе | Используется externalId, который уже есть в системе (дубль). Сгенерируйте новый externalId и повторите запрос. | |
Отсутствует доступный открытый рублевый расчетный счет у организации плательщика | Плательщику требуется открыть рублевый расчетный счет в Сбербанке. | |
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": "145ac7ed-9c20-4a75-8135-8a978d403836",
"message": "Объект Invoice не соответствует модели",
"checks": [
{
"level": "ERROR",
"message": "должно соответствовать \"^(электронно|срочно|0)$\"",
"fields": [
"deliveryKind"
]
}
],
"fieldNames": [
"deliveryKind"
]
}
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_INVOICE_BUDGET . Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token. |
Вы использовали access_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": "Внутренняя ошибка сервера"
}
Получить статус платежного поручения
/v1/payments/{externalId}
Ресурс позволяет вам получить статус ранее сформированного черновика платежного поручения. В случае, если у Клиента отключена/истек срок соглашения услуги на формирование платежных поручений, вы все равно сможете получить статус готовых документов.
Для получения статуса необходимо отправить GET-запрос /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/fintech/api
- Промышленный контур
https://fintech.sberbank.ru:9443/fintech/api
Request
/v1/payments/{externalId}/state
- Модель
- Пример
Наименование | Тип | Формат | Regexp | Обязательность | Описание |
---|---|---|---|---|---|
HEADER | |||||
Authorization | string | string | ^([a-zA-Z0-9]){38}$ | required | Access token пользователя, полученный через SSO. |
PATH PARAMETERS | |||||
externalId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | required | Идентификатор документа, присвоенный вами при создании счета |
GET /fintech/api/v1/payments/6a54593d-464b-4c8e-a7e2-742a05e5c241/state HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
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. |
Вы использовали access_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 | Одобрен ФРОД | Проверка во ФРОДЕ прошла успешно, переход на «Принят» |
FRAUDDENY | Отвергнут ФРОД | Документ отказан на основе проверки в АС Fraud-мониторинг, переходим в «Отвергнут банком» |
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 | Отказан контролирующей организацией | Электронный документ не прошел проверки контролирующей организацией |
Окончательный (Успешный)/Прекратить опрос | ||
IMPLEMENTED | Исполнен | Электронный документ исполнен Банком |
Получить атрибуты поручения
/v1/payments{externalId}
Ресурс позволяет вам получить атрибуты ранее сформированного черновика платежного поручения.
Для получения атрибутов платежного поручения необходимо отправить GET-запрос /v1/payments/{externalId}
с токеном доступа (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/fintech/api
- Промышленный контур
https://fintech.sberbank.ru:9443/fintech/api
Request
/v1/payments/{externalId}
- Модель
- Пример
Наименование | Тип | Формат | Regexp | Обязательность | Описание |
---|---|---|---|---|---|
HEADER | |||||
Authorization | string | string | ^([a-zA-Z0-9]){38}$ | required | Access token пользователя, полученный через SSO. |
PATH PARAMETERS | |||||
externalId | string | UUID | ^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})$ | required | Идентификатор документа, присвоенный вами при создании счета |
GET /fintech/api/v1/payments/6a54593d-464b-4c8e-a7e2-742a05e5c241 HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Responses
200 (ОК)
- Модель
- Пример
Наименование | Тип | Обязательность | Описание |
---|---|---|---|
Payment { | |||
amount | number | required | Сумма платежа, |
bankComment | string | optional | Банковский комментарий к статусу документа, |
bankStatus | string | optional | Статус документа, |
crucialFieldsHash | string | optional | Hash от ключевых полей документа, |
date | string | required | Дата составления документа, |
deliveryKind | string | optional | Вид платежа, |
departmentalInfo | Array[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. |
Вы использовали access_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_рубля
.
FAQ
Какой максимальный срок жизни можно установить для платежного поручения?
Пунктами 5.5, 7.7, 9.6 Положения 383-П установлено, что платежные поручения, инкассовые поручения, платежные требования действительны для представления в банк в течение 10 календарных дней со дня их составления, то есть исчисление срока начинается на следующий день после их составления.
Дата истечения заказа устанавливается в соответствие с вашими бизнес-задачами вами атрибутом expirationDate в ресурсах /v1/payments/from-invoice
и /v1/payments/from-invoice-any
.
Крайний срок действия платежного поручения от даты его формирования не может превышать 10 календарных дней.
Как отозвать сформированный черновик платежного поручения?
Отозвать сформированный черновик платежного поручения на вашей стороне нет технической возможности.
При использовании ресурсов "Моментальные платежи", которые создают черновики платежных поручений, черновики также появляются в СберБизнес Клиента. Через СберБизнес Клиент может самостоятельно отклонить черновик.
Как быстро Банк исполняет подписанное платежное поручение?
После подписания черновика платежного поручения Банк проводит ряд проверок. Обычно Банк исполняет подписанное платежное поручение в течение 1 минуты. В ряде случаев может потребоваться дополнительная информация от Клиента, что увеличит время исполнения документа.
Еще подробнее об исполнении и зачислении платежей в Справочном центре для бизнеса.
Откуда Банк берет реквизиты отправителя для платежного поручения?
В рамках сервиса СберБизнес ID вы реализуете механизм получения access_token. При формировании платежного поручения вы передаете с другими атрибутами access_token, по которому Банк самостоятельно в платежное поручение подставляет все реквизиты плательщика (отправителя).
Где взять access_token?
Получение access_token необходимо реализовать в рамках сервиса СберБизнес ID.
Что будет, если Клиент покинет страницу оплаты, не подписав черновик платежного поручения?
При использовании ресурсов "Моментальные платежи", которые создают черновики платежных поручений, черновики также появляются в СберБизнес Клиента. Любой пользователь Клиента, который имеет право подписи черновиков платежных поручений, сможет подписать черновик.