Черновик платежного документа

Обновлено 14 июля 2023

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

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

Создание дебетовых поручений

Ресурс /v1/payments позволяет Партнеру создавать дебетовые платежные поручения по счетам клиента. Реквизиты получателя документа доступны для редактирования клиенту.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для создания черновика необходимо отправить POST-запрос (/v1/payments), в котором передать авторизационный токен к данным клиента (Access Token) и реквизиты платежного поручения. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAY_DOC_RU.

Модель запроса и ответа

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации-клиента, полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры тела запроса
Payment {
amount (number)	Сумма платежа,
bankComment (string, optional, read only)	Банковский комментарий к статусу документа,
bankStatus (string, optional, read only)	Статус документа,
crucialFieldsHash (string, optional, read only)	Hash от ключевых полей документа,
date (string)	Дата составления документа,
deliveryKind (string, optional)	Вид платежа: электронно, срочно Если не заполнено или 0, то будет присвоено значение "электронно",
departmentalInfo (DepartmentalInfo, optional)	Реквизиты налогового, таможенного или иного бюджетного платежа,
digestSignatures (Array[Signature], optional)	Электронные подписи по дайджесту документа,
externalId (string)	Идентификатор документа, присвоенный партнером (UUID),
incomeTypeCode (string, optional)	Код вида дохода получателей выплаты по 229-ФЗ. Коды: 1 - При переводе денежных средств, являющихся заработной платой и (или) иными доходами, в отношении которых статьей 99 Федерального закона N 229-ФЗ установлены ограничения, 2 - При переводе денежных средств, являющихся доходами, на которые в соответствии со статьей 101 Федерального закона N 229-ФЗ не может быть обращено взыскание, за исключением доходов, указанных в пунктах 1 и 4 части 1 статьи 101 Федерального закона N 229-ФЗ), 3 - При переводе денежных средств, являющихся видами доходов, на которые в соответствии с пунктами 1 и 4 части 1 статьи 101 Федерального закона N 229- ФЗ не может быть обращено взыскание,
number (string, optional)	Номер документа Обратите внимание: номер документа должен быть не более 6 цифр,
operationCode (string)	Код операции: 1
payeeAccount (string, optional)	Счет получателя платежа,
payeeBankBic (string)	БИК получателя платежа,
payeeBankCorrAccount (string, optional)	Корсчет банка получателя платежа,
payeeInn (string, optional)	ИНН получателя платежа,
payeeKpp (string, optional)	КПП получателя платежа,
payeeName (string)	Полное наименование получателя платежа,
payerAccount (string)	Счет плательщика,
payerBankBic (string)	БИК банка плательщика,
payerBankCorrAccount (string)	Корсчет банка плательщика,
payerInn (string)	ИНН плательщика,
payerKpp (string, optional)	КПП плательщика,
payerName (string)	Полное наименование плательщика,
priority (string)	Очередность платежа: 1, 2, 3, 4, 5,
purpose (string)	Назначение платежа Размерность: [1 .. 210],
urgencyCode (string, optional)	Код срочности = [`INTERNAL` - срочный, `INTERNAL_NOTIF` - срочный платеж с уведомлением, `OFFHOURS` - неотложный, `BESP` - банковские электронные срочные платежи, `NORMAL` - срочность не указана] stringEnum: 0, 1, 2, 3, 4,
vat (Vat, optional)	Данные НДС,
voCode (string, optional)	Код вида валютной операции
}DepartmentalInfo {
uip (string, optional)	Уникальный идентификатор платежа,
drawerStatus101 (string, optional)	Показатель статуса налогоплательщика (реквизит - 101),
kbk (string, optional)	Код бюджетной классификации (реквизит - 104),
oktmo (string, optional)	Код OKTMO (реквизит - 105),
reasonCode106 (string, optional)	Показатель основания платежа (реквизит - 106),
taxPeriod107 (string, optional)	Налоговый период / код таможенного органа (реквизит - 107),
docNumber108 (string, optional)	Номер налогового документа (реквизит - 108) Должно быть проставлено значение: 0 или пустое или цифровое,
docDate109 (string, optional)	Дата налогового документа (реквизит - 109),
paymentKind110 (string, optional)	Тип налогового платежа (реквизит - 110)
}Signature {
base64Encoded (string)	Значение электронной подписи, закодированное в Base64,
certificateUuid (string)	Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}Vat {
amount (number, optional)	Сумма НДС,
rate (string, optional)	Ставка НДС: 0,10,20,
type (string)	Способ расчета НДС = [`INCLUDED` - НДС включен в сумму платежа, `NO_VAT` - не облагается НДС, `MANUAL` - ручной ввод НДС] stringEnum: "0", "2", "3"
}

Пример запроса

{
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "date":"2018-12-31",
   "deliveryKind":"электронно",
   "departmentalInfo":{
      "uip":"0",
      "drawerStatus101":"01",
      "kbk":"18210102010011000110",
      "oktmo":"01701000",
      "reasonCode106":"ТП",
      "taxPeriod107":"ГД.00.2018",
      "docNumber108":"123",
      "docDate109":"0",
      "paymentKind110":"1"
   },
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "incomeTypeCode":"2",
   "number":"1",
   "operationCode":"01",
   "payeeAccount":"40802810600000200000",
   "payeeBankBic":"044525225",
   "payeeBankCorrAccount":"30101810400000000225",
   "payeeInn":"7707083893",
   "payeeKpp":"222201001",
   "payeeName":"Общество с ограниченной ответственностью \"Клиент\"",
   "payerAccount":"40802810600000200000",
   "payerBankBic":"044525225",
   "payerBankCorrAccount":"30101810400000000225",
   "payerInn":"7707083893",
   "payerKpp":"222201001",
   "payerName":"Общество с ограниченной ответственностью \"Клиент\"",
   "priority":"5",
   "purpose":"Оплата заказа №123. НДС нет.",
   "urgencyCode":"INTERNAL",
   "vat":{
      "amount":0.00,
      "rate":"0",
      "type":"NO_VAT"
   },
   "voCode":"61150"
}

Если требуется проверить неизменность реквизитов получателя платежа до получения выписки с информацией о проведенном документе, необходимо сравнить хэш реквизитов получателя (crucialFieldsHash), полученный при создании черновика документа, с crucialFieldsHash полученным при запросе статуса документа. Для вычисления значения хэша ключевых полей формируется строка из реквизитов, соединенных между собой: БИК банка получателя, счет получателя платежа, сумма платежа, (разделитель-точка).

Получение статуса документа

Ресурс /v1/payments/{externalId}/state позволяет получить статус ранее отправленного черновика документа.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения статуса необходимо отправить GET-запрос (/v1/ payments/{externalId}/state), в котором передать авторизационный токен к данным клиента (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAY_DOC_RU.

Модель запроса

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации-клиента, полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
externalId (String)	Идентификатор документа, присвоенный клиентом

Пример запроса

curl -X GET --header 'Accept: /' --header 'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payments/ffffffff-fffa-458e-ad92-fff9497303ba/state'

Модель ответа

Наименование	Описание
PaymentDocState {
bankComment (string, optional, read only)	Банковский комментарий к статусу документа,
bankStatus (string, optional)	Статус документа,
channelInfo (string, optional, read only)	Комментарий, специфичный для документа, полученного по данному каналу,
crucialFieldsHash (string, optional)	Hash от ключевых полей документа
}

Пример ответа

{
"bankStatus": "CREATED",
"bankComment": null,
"channelInfo": null,
"crucialFieldsHash": "4888bdfe92812ebf1f70aa9be4b8a733"
}

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

Код состояние документа	Наименование статуса	Назначение кода состояния
	Промежуточный/Продолжать опрашивать
`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} позволяет Партнеру получить ранее отправленное рублевое платежное поручение.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения платежного поручения необходимо отправить GET-запрос (/v1/payments/{externalId}), в котором необходимо передать авторизационный токен к данным клиента (Access Token) и внешний идентификатор платежного поручения. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAY_DOC_RU.

Модель запроса и ответа

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации-клиента, полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
externalId (String)	Идентификатор документа, присвоенный партнером

Пример запроса

curl -X GET --header 'Accept: /' --header 'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payments/ffffffff-fffa-458e-ad92-fff9497303ba/state'

Модель ответа

Соответствует модели запроса и ответа /v1/payments.

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

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

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

Если блок vat не указан, то по умолчанию будут присвоены и придут в ответе на запрос следующие значения :

"vat": {
 "type": "NO_VAT",
 "rate": "0",
 "amount": "0.00"
}

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

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

Подписание запроса транспортной подписью

Content-Type может содержать одно из двух значений:

application/json – запрос без подписи
application/jose – запрос, подписанный транспортной подписью

Если Content-Type имеет значение application/jose, то запрос должен содержать данные (реквизитный состав платежного документа) в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из:

1. Заголовка (Header)
2. JSON-документа с реквизитным составом платежного поручения (Payload)
3. Подписи запроса (Signature)

Формирование компактной сериализации JW

JWS формируется из трех составляющих:

Base64Url(Header) || ’.’ ||  Base64Url(Payload) || ’.’ || Base64Url(Signature)

Signature - это подпись данных приватной частью ключевой пары клиента (используется приватный ключ парный сертификату клиента с UUID, указанному в Заголовке (Header) в параметре kid).
Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg, в данном случае gost34.10-2012, и вычисляется от исходных данных:

Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

Следует отметить, что при кодировании JWS используется преобразование Base64Url, отличающееся от Base64 преобразования.
Условно это преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

здесь функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x, функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование BASE64URL, отличается от BASE64 преобразования:

Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.

BASE64URL	BASE64
- (minus)	+
_ (underline)	/

В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

Коды возврата

Код возврата	Описание кода возврата	Причина возникновения
200 (GET-запрос)	`ОК`
201 (POST-запрос)	`CREATED`
	Создан
400	`DESERIALIZATION_FAULT`
	Неверный формат запроса	Неверный формат запроса
	`WORKFLOW_FAULT`
	Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ	Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
	Документ с такими реквизитами уже существует	Документ с такими реквизитами уже существует. Проверка по номер документа в течении года.
	Не указан идентификатор сертификата подписи	Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
	Некорректный формат параметра kid заголовка JWS	Некорректный формат параметра kid заголовка JWS(ожидается UUID)
	`VALIDATION_FAULT`
	Ошибка валидации	Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
	`SIGN_CHECK_EXCEPTION`
	Подлинность подписи не установлена/Сертификат не обнаружен или не является активным	Ошибка возникает, если не удалось установить подлинность подписи
401	`UNAUTHORIZED`
	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token.
403	`ACTION_ACCESS_EXCEPTION`
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404	`DATA_NOT_FOUND_EXCEPTION`
	Платежный документ не найден	Неверное значение externalId
415	`JWS_EXCEPTED`
	В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization	Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500	`UNKNOWN_EXCEPTION`
	Внутренняя ошибка сервера

Черновик платежного документа

Создание дебетовых поручений﻿

Шаги﻿

Модель запроса и ответа﻿

Пример запроса﻿

Получение статуса документа﻿

Шаги﻿

Модель запроса﻿

Пример запроса﻿

Модель ответа﻿

Пример ответа﻿

Статусы обработки платежных документов﻿

Получение отправленного поручения﻿

Шаги﻿

Модель запроса и ответа﻿

Пример запроса﻿

Модель ответа﻿

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

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

Подписание запроса транспортной подписью﻿

Формирование компактной сериализации JW﻿

Коды возврата﻿

Создание дебетовых поручений

Шаги

Модель запроса и ответа

Пример запроса

Получение статуса документа

Шаги

Модель запроса

Пример запроса

Модель ответа

Пример ответа

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

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

Шаги

Модель запроса и ответа

Пример запроса

Модель ответа

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

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

Подписание запроса транспортной подписью

Формирование компактной сериализации JW

Коды возврата