Входящие платежные требования

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

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

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

Создание заявления об акцепте

Ресурс /v1/acceptance-letters позволяет создать заявление об акцепте/отказе от акцепта входящего платежного требования.

Шаги

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

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

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

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

Авторизация

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token, полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
AcceptanceLetter
amount (number)	Сумма акцепта
bankComment (string, optional, read only)	Банковский комментарий к статусу документа
bankStatus (string, optional, read only)	Статус документа
date (string)	Дата составления документа
digestSignatures (Array[Signature], optional)	Электронные подписи по дайджесту документа
externalId (string)	Идентификатор документа в организации-партнере (UUID)
nonAcceptReason (string)	Причина отказа
number (string, optional)	Номер документа
payReqAmount (number)	Сумма платежного требования
payReqDate (string)	Дата платежного требования
payReqExternalId (string)	Идентификатор платежного требования
payReqLastDate (string)	Дата окончания акцепта
payReqNumber (string)	Номер платежного требования
payeeAccount (string)	Счет получателя платежа
payeeBankBic (string)	БИК получателя платежа
payeeBankCorrAccount (string)	Корсчет банка получателя платежа
payeeInn (string)	ИНН получателя платежа
payeeName (string)	Полное наименование получателя платежа
payerAccount (string)	Счет плательщика
payerBankBic (string)	БИК банка плательщика
payerInn (string)	ИНН плательщика
payerName (string)	Полное наименование плательщика
type (string)	Тип заявления = ['accept', 'nonAccept'] stringEnum: "accept", "nonAccept"
Signature
base64Encoded (string)	Значение электронной подписи, закодированное в Base64
certificateUuid (string)	Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)

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

{
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "date":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "nonAcceptReason":"string",
   "number":"1",
   "payReqAmount":1.01,
   "payReqDate":"2018-12-31",
   "payReqExternalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "payReqLastDate":"2018-12-31",
   "payReqNumber":"2",
   "payeeAccount":"40802810600000200000",
   "payeeBankBic":"044525225",
   "payeeBankCorrAccount":"30101810400000000225",
   "payeeInn":"7707083893",
   "payeeName":"Общество с ограниченной ответственностью \"Клиент\"",
   "payerAccount":"40802810600000200000",
   "payerBankBic":"044525225",
   "payerInn":"7707083893",
   "payerName":"Общество с ограниченной ответственностью \"Клиент\"",
   "type":"accept"
}

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

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

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

Для платежных поручений, создаваемых по собственным счетам, можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:

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

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

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

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

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

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

Наименование	Описание	Пример
externalId	Идентификатор документа в организации-партнере (UUID)	550e8400-e29b-41d4-a716-446655440000
date	Дата составления документа	2019-09-20
type	Тип заявления	accept
amount	Сумма акцепта	100.01
payeeAccount	Счет получателя платежа	40702810500000006103
payeeBankBic	БИК получателя платежа	044525411
payeeBankCorrAccount	Корсчет банка получателя платежа	30101810400000000225
payeeInn	ИНН получателя платежа	222201236445
payeeName	Полное наименование получателя платежа	Общество с ограниченной ответственностью «Получатель»
payerAccount	Счет плательщика	40702810500000006109
payerBankBic	БИК банка плательщика	044525411
payerInn	ИНН плательщика	222201236449
payerName	Полное наименование плательщика	Общество с ограниченной ответственностью «Плательщик»
payReqNumber	Номер платежного требования	2
payReqDate	Дата платежного требования	2019-09-20
payReqAmount	Сумма платежного требования	100.01
payReqLastDate	Дата окончания акцепта	2019-09-21

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

externalId=550e8400-e29b-41d4-a716-446655440000
date=2019-09-20
type=accept
amount=100.01
payeeAccount=40702810500000006103
payeeBankBic=044525411
payeeBankCorrAccount=30101810400000000225
payeeInn=222201236445
payeeName=Общество с ограниченной ответственностью "Получатель"
payerAccount=40702810500000006109
payerBankBic=044525411
payerInn=222201236449
payerName=Общество с ограниченной ответственностью "Плательщик"
payReqNumber=2
payReqDate=2019-09-20
payReqAmount=100.01
payReqLastDate=2019-09-21

Получение статуса заявления

Ресурс /v1/acceptance-letters/{externalId}/state позволяет получить статус отправленного запроса на создание заявления об акцепте/отказе от акцепта входящего платежного требования.

Шаги

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

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

Авторизация

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1`
Параметры запроса
externalId (String)	Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/acceptance-letters/1550ff04-07d6-427b-8c25-27484e8cc830/state'

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

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

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

{
   "bankStatus":"DELIVERED",
   "bankComment":null,
   "channelInfo":null
}

Возможные статусы

Статус	Значение	Комментарий
`DELIVERED`	Доставлен	Промежуточный/Продолжать опрашивать
`VALIDEDS`	ЭП/АСП верна	Промежуточный/Продолжать опрашивать
`INVALIDEDS`	ЭП/АСП не верна	Конечный/Прекратить опрашивать
`REQUISITEERROR`	Ошибка реквизитов	Конечный/Прекратить опрашивать
`TRIED`	Проверен	Промежуточный/Продолжать опрашивать
`DELAYED`	Приостановлен	Промежуточный/Продолжать опрашивать
`CORRESPONDENT_APPROVE_WAITING`	Ожидает подтверждения контрагента	Промежуточный/Продолжать опрашивать
`EXPORTED`	Выгружен	Промежуточный/Продолжать опрашивать
`IMPLEMENTED`	Исполнен	Успешный конечный/Прекратить опрашивать
`REFUSEDBYABS`	Отказан АБС	Конечный/Прекратить опрашивать
`ACCEPTED`	Принят	Промежуточный/Продолжать опрашивать
`ACCEPTED_BY_ABS`	Принят АБС	Промежуточный/Продолжать опрашивать
`CARD2`	Картотека №2	Промежуточный/Продолжать опрашивать
`SIGNED_BANK`	Подписан Банком	Промежуточный/Продолжать опрашивать
`SIGNED`	Подписан	Промежуточный/Продолжать опрашивать
`UNABLE_TO_RECEIVE`	Ошибка при приеме	Промежуточный/Продолжать опрашивать
`CREATED`	Создан	Промежуточный/Продолжать опрашивать
`IMPORTED`	Импортирован	Промежуточный/Продолжать опрашивать
`PARTSIGNED`	Частично подписан	Промежуточный/Продолжать опрашивать
`CHECKERROR`	Ошибка контроля	Конечный/Прекратить опрашивать
`TEMPLATE`	Шаблон документа	Промежуточный/Продолжать опрашивать
`REFUSEDBYBANK`	Отвергнут Банком	Конечный/Прекратить опрашивать
`RECALL`	Отозван	Конечный/Прекратить опрашивать

Получение входящих поручений

Ресурс /v1/payment-requests/incoming позволяет получить входящие платежные поручения за указанную дату.

Шаги

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

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

Авторизация

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

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

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

Наименование	Описание
Параметры заголовка
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/payment-requests/incoming?date=ffffffff-fffa-458e-ad92-ff9497303ba&page=1'

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

Наименование	Описание
PaymentRequestsInInfo
_links (Array[Link], optional)	Ссылки на связанные ресурсы
paymentsRequestIn (Array[PaymentRequestsIn], optional)	Входящие платежные требования
Link
href (string)	Абсолютный или относительный адрес
rel (string)	Отношение ссылки к текущей сущности (next, prev)
PaymentRequestsIn
acceptLastDate (string, optional)	Дата окончания акцепта
acceptanceTerm (string, optional)	Срок для акцепта (поле 36)
amount (number, optional)	Сумма платежа
bankComment (string, optional, read only)	Банковский комментарий к статусу документа
bankStatus (string, optional, read only)	Статус документа
date (string)	Дата составления документа
deliveryKind (string, optional)	Вид платежа
externalId (string, optional)	Идентификатор документа, присвоенный партнером (UUID)
number (string, optional)	Номер документа
operationCode (string, optional)	Код операции
payeeAccount (string, optional)	Счет получателя платежа
payeeBankBic (string, optional)	БИК получателя платежа
payeeBankCorrAccount (string, optional)	Корсчет банка получателя платежа
payeeInn (string, optional)	ИНН получателя платежа
payeeName (string, optional)	Полное наименование получателя платежа
payerAccount (string, optional)	Счет плательщика
payerBankBic (string, optional)	БИК банка плательщика
payerBankCorrAccount (string, optional)	Корсчет банка плательщика
payerInn (string, optional)	ИНН плательщика
payerName (string, optional)	Полное наименование плательщика
paymentCondition (string, optional)	Условие оплаты (поле 35). Указывается цифра "1" -заранее данный акцепт плательщика или цифра "2" - требуется получение акцепта плательщика
priority (string, optional)	Очередность платежа
purpose (string, optional)	Назначение платежа
vat (Vat, optional)	Данные НДС
Vat
amount (number, optional)	Сумма НДС
rate (string, optional)	Ставка НДС
type (string)	Способ расчета НДС = [`INCLUDED`, `NO_VAT`, `MANUAL`] stringEnum:`INCLUDED`, `NO_VAT`, `MANUAL`

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

{
   "_links":[
      {
         "href":"?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
         "rel":"next"
      }
   ],
   "paymentsRequestIn":[
      {
         "acceptLastDate":"2018-12-31",
         "acceptanceTerm":"20",
         "amount":1.01,
         "bankComment":"string",
         "bankStatus":"string",
         "date":"2018-12-31",
         "deliveryKind":"электронно",
         "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
         "number":"1",
         "operationCode":"01",
         "payeeAccount":"40802810600000200000",
         "payeeBankBic":"044525225",
         "payeeBankCorrAccount":"30101810400000000225",
         "payeeInn":"7707083893",
         "payeeName":"Общество с ограниченной ответственностью \"Клиент\"",
         "payerAccount":"40802810600000200000",
         "payerBankBic":"044525225",
         "payerBankCorrAccount":"30101810400000000225",
         "payerInn":"7707083893",
         "payerName":"Общество с ограниченной ответственностью \"Клиент\"",
         "paymentCondition":"1",
         "priority":"5",
         "purpose":"Оплата заказа №123. НДС нет.",
         "vat":{
            "amount":1.01,
            "rate":"7",
            "type":"NO_VAT"
         }
      }
   ]
}

Получение статуса

Ресурс /v1/payment-requests/incoming/{externalId}/state позволяет получить статус входящего платежного требования.

Шаги

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

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

Авторизация

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1`
Параметры запроса
externalId (String)	Идентификатор документа,присвоенный клиентом

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payment-requests/incoming/1550ff04-07d6-427b-8c25-27484e8cc830/state'

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

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

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

{
   "bankStatus":"DELIVERED",
   "bankComment":null,
   "channelInfo":null
}

Возможные статусы

Статус	Значение	Состояние
`CREATED`	Создан	Промежуточный/Продолжать опрашивать
`ACCEPTANCE`	Акцептован	Конечный/Прекратить опрашивать
`PARTACCEPT`	Частично акцептован	Промежуточный/Продолжать опрашивать
`CARD2`	Картотека №2	Промежуточный/Продолжать опрашивать
`PROCESSERROR`	Отказан	Конечный/Прекратить опрашивать
`IMPLEMENTED`	Исполнен	Успешный конечный/Прекратить опрашивать
`PROCESSING`	В обработке	Промежуточный/Продолжать опрашивать
`ONACCEPTANCE`	На акцепт	Промежуточный/Продолжать опрашивать
`READY_TO_SEND`	Ждет отправки	Промежуточный/Продолжать опрашивать
`DELIVERED`	Доставлен	Промежуточный/Продолжать опрашивать
`REQUISITEERROR`	Ошибка реквизитов	Конечный/Прекратить опрашивать
`CHECKERROR`	Ошибка контроля	Промежуточный/Продолжать опрашивать
`TEMPLATE`	Шаблон документа	Промежуточный/Продолжать опрашивать
`ACCEPTED`	Принят	Промежуточный/Продолжать опрашивать
`ACCEPTEXPIRE`	Истек срок акцепта	Конечный/Прекратить опрашивать
`NONEACCEPTANCE`	Отказ от акцепта	Конечный/Прекратить опрашивать
`PAID`	Оплачено	Промежуточный/Продолжать опрашивать

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

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

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

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

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

JWS состоит из:

заголовка (Header),
JSON-документа с реквизитным составом платежного поручения (Payload),
подписи запроса (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 преобразования:

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

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

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

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

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

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

Входящие платежные требования

Создание заявления об акцепте﻿

Шаги﻿

Авторизация﻿

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

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

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

Формат дайджеста﻿

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

Получение статуса заявления﻿

Шаги﻿

Авторизация﻿

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

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

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

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

Возможные статусы﻿

Получение входящих поручений﻿

Шаги﻿

Авторизация﻿

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

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

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

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

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

Шаги﻿

Авторизация﻿

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

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

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

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

Возможные статусы﻿

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

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

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

Создание заявления об акцепте

Шаги

Авторизация

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

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

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

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

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

Получение статуса заявления

Шаги

Авторизация

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

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

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

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

Возможные статусы

Получение входящих поручений

Шаги

Авторизация

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

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

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

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

Получение статуса

Шаги

Авторизация

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

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

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

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

Возможные статусы

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

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

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