ym88659208ym87991671
Входящие платежные требования для холдингов | Документация SmartMarket
Skip to main content

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

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

  • Тестовый контур https://edupirfintech.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 может содержать одно из двух значений:

1. application/json – запрос без подписи.

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

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

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

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

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

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

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