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

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

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

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

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

Шаги

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

2. Сформировать ЭП.

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

4. Получить статус.

5. Получить документ.

Для создания рублевого платежного поручения необходимо отправить 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) Номер документа,
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) Назначение платежа,
urgencyCode (string, optional) Код срочности = ['INTERNAL' - срочный, 'INTERNAL_NOTIF' - срочный платеж с уведомлением, 'OFFHOURS' - неотложный, 'BESP' - банковские электронные срочные платежи, 'NORMAL' - срочность не указана]
stringEnum: 1, 2, 3, 4, 5,
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),
docDate109 (string, optional) Дата налогового документа в формате YYYY-MM-DD (реквизит - 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":"2017.01.01",
      "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 полученным при запросе статуса документа. Для вычисления значения хэша ключевых полей формируется строка из реквизитов, соединенных между собой: БИК банка получателя, счет получателя платежа, сумма платежа, (разделитель-точка).

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

Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature:

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

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

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

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

При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.

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

Формат дайджеста РПП

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

Пример дайджеста

amount=100.00
date=2018-05-31
departmentalInfo.docNumber108=123
departmentalInfo.drawerStatus101=01
departmentalInfo.kbk=18210102010011000110
departmentalInfo.oktmo=01701000
departmentalInfo.paymentKind110=НС
departmentalInfo.reasonCode106=ТП
departmentalInfo.uip=0
externalId=a0000000-0000-0000-0000-000000000001
incomeTypeCode=2
operationCode=01
payeeAccount=40702810600100001212
payeeBankBic=044525225
payeeBankCorrAccount=30101810400000000225
payeeInn=222201236445
payeeKpp=222201001
payeeName=Общество с ограниченной ответственностью "Получатель"
payerAccount=40702810500006103990
payerBankBic=044525225
payerBankCorrAccount=30101810400000000225
payerInn=222201236445
payerKpp=222201001
payerName=Общество с ограниченной ответственностью "Клиент"
priority=5
purpose=Оплата интернет заказа №123. НДС нет.
voCode=61150

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

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

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

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 преобразования:

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 (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404 DATA_NOT_FOUND_EXCEPTION
Платежный документ не найден Неверное значение externalId
415 JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней