Сервис гарантированных расчетов

Назначение

Ресурсы предоставляют возможность блокировать деньги на расчетных счетах плательщиков, а потом списывать их или возвращать. Двухэтапная оплата подходит компаниям, которые работают по предоплате или хотят убедиться в платежеспособности клиента.

Все запросы данного раздела направляются на адреса:

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

Схема процесса

  • Направьте клиента на форму подписания оферты и ЗДА (ссылка)
  • Получите ЗДА клиента GET /v1/partner-info/advance-acceptances
  • Забронируйте денежные средства (далее ДС) POST /v1/cash-hold/hold
  • Получите статус запроса на бронирование ДС GET /v1/cash-hold/hold/{externalId}/state

    • Если статус FUNDS_FULLY_HELD - ДС забронированы, переходите к переводу забронированных средств.
    • Если статус обработки запроса завершился одним из негативных статусов - можно повторить запрос бронирования при необходимости.
  • Если клиент отказывается от услуги, выполните отмену POST /v1/cash-hold/unhold
  • Получите статус отмены бронирования GET /v1/cash-hold/unhold/{externalId}/state

    • Если статус PROCESSED - бронь отменена.
    • Если статус обработки запроса бронирования средств завершился одним из негативных статусов - можно повторить запрос отмены бронирования средств.
  • Переведите забронированные средства на счет партнера POST /v1/cash-hold/unhold-transfer

    • Если сумма забронированных ДС переводится полностью, перейдите к шагу получения статуса запроса.
    • Если сумма забронированных ДС переводится частично, перейдите к шагу отмены не используемых ДС.
  • Получите статуса перевода ДС GET /v1/cash-hold/unhold-transfer/{externalId}/state

    • Если статус PROCESSED - ДС переведены партнеру.
    • Если статус обработки запроса завершился одним из негативных статусов - можно повторить запрос перевода забронированных средств.

Сценарий сервиса гарантированных расчетов

Получение сведений о клиентах

Ресурс /v1/partner-info/advance-acceptances позволяет Партнеру получить сведения о клиентах, подключенных к подпискам и пакетам услуг. Полученную информацию можно анализировать и использовать для выставления платежных требований в адрес клиентов сервиса. В ответе возвращается информация за один запрашиваемый день. Для поддержания актуальной информации и изменений на своей стороне необходимо осуществлять ежедневный запрос информации.

Шаги

1. При авторизации пользователя партнера передать в scope сервис GET_ADVANCE_ACCEPTANCES.

2. Отправить GET-запрос (/v1/partner-info/advance-acceptances), с Access token пользователя партнера. Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token организации-клиента, полученный через SSO. Пример: Bearer 5c2f4c8d-4c8a-4301-8df7-195354932b19-1
Параметры запроса
date (date-time) Дата (подключения или отключения)
Формат: yyyy-MM-dd
clientId (String) Идентификатор сервиса

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

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 5c2f4c8d-4c8a-4301-8df7-195354932b19-1'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/partner-info/advance-acceptances?date=2019-10-24'

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

Наименование Описание
AdvanceAcceptance [
AdvanceAcceptance 1
] AdvanceAcceptance 1{
active (boolean, optional) Признак активности ЗДА ,
bundles (Array[AdvanceAcceptanceBundle], optional) Информация о пакете услуг,
payerAccount (string, optional) Счёт плательщика ,
payerBankBic (string, optional) БИК банка плательщика ,
payerBankCorrAccount (string, optional) Корсчёт банка плательщика ,
payerInn (string, optional) ИНН плательщика ,
payerName (string, optional) Наименование плательщика ,
payerOrgIdHash (string, optional) Идентификатор организации плательщика ,
purpose (string, optional) Назначение платежа ,
sinceDate (string, optional) Дата начала действия заранее данного акцепта ,
untilDate (string, optional) Дата окончания действия заранее данного акцепта
}AdvanceAcceptanceBundle {
code (string, optional) Код пакета услуг ,
name (string, optional) Наименование пакета услуг,
sinceDate (string, optional) Дата подключения пакета услуг ,
untilDate (string, optional) Дата отключения пакета услуг,
currentState (String, optional) Статус пакета услуг в настоящее время.
Возможные варианты: ACTIVE, NOT_PAID, DEACTIVATED
}

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

{
   "active":false,
   "bundles":[
      {
         "code":"POLNHODB",
         "name":"Полным ходом",
         "sinceDate":"2018-12-31",
         "untilDate":"2018-12-31",
         "currentState":"ACTIVE"
      }
   ],
   "payerAccount":"40802810600000200000",
   "payerBankBic":"044525225",
   "payerBankCorrAccount":"40802810600000200000",
   "payerInn":"7707083893",
   "payerName":"Общество с ограниченной ответственностью \"Клиент\"",
   "payerOrgIdHash":"ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5",
   "purpose":"Оплата заказа №123. НДС нет.",
   "sinceDate":"2018-12-31",
   "untilDate":"2018-12-31"
}

Бронирование средств на счете клиента

Ресурс /v1/cash-hold/hold позволяет Партнеру отправить запрос на бронирование денежных средств на счете клиента для гарантии оплаты за предоставленные услуги.

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

Шаги

1. При авторизации пользователя партнера передать в scope сервис CASH_HOLD.

2. Отправить POST-запрос (/v1/cash-hold/hold), с Access token пользователя партнера. Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
CashHoldRequest {
account (string) Счет агента, на котором будет осуществляться блокировка ,
amount (number) Сумма бронирования ,
bankComment (string, optional, read only) Банковский комментарий к статусу документа ,
bankStatus (string, optional, read only) Статус документа ,
clientId (integer) Идентификатор сервиса, используемый для взаимодействия с агентом ,
datetimeUnhold (string) Дата и время автоматической отмены бронирования денежных средств,
указывается московское время UTC+3:00 (yyyy-MM-dd'T'HH:mm:ss),
digestSignatures (Array[Signature]) Электронные подписи по дайджесту документа ,
externalId (string) Идентификатор документа, присвоенный партнёром (UUID) ,
hashOrgId (string) Хэш идентификатора организации агента ,
reasonId (string, optional) Идентификатор бронирования (используется при формировании основания бронирования денежных средств. Не более 25 символов)
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
   "account":"40802810600000200000",
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "clientId":1005,
   "datetimeUnhold":"yyyy-MM-dd'T'HH:mm:ss",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "hashOrgId":"ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5",
   "reasonId":"201910041706"
}

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

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

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

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

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

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

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

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

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

Наименование поля Описание поля
account Счета агента, на котором будет осуществляться бронирование
amount Сумма бронирования
clientId Идентификатор сервиса, используемый для взаимодействия с Агентом
datetimeUnhold Дата и время автоматической отмены бронирования забронированных средств, указывается московское время UTC+3:00
externalId Идентификатор запроса на бронирование, присвоенный партнером
hashOrgId Хэш от идентификатора организации
reasonId Идентификатор бронирования
(используется при формировании основания бронирования денежных средств. Не более 25 символов)

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

account=4070281010102000012
amount=100.00
clientId=1234
datetimeUnhold=2019-10-27T14:00:00
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
hashOrgId=b34b6a4533862e5167e98785b1d23aa789dac2160b3c7c9cc39221bd33ffc85a
reasonId=201910041706

Получение статуса на бронирование средств

Ресурс /v1/cash-hold/hold/{externalId}/state позволяет Партнеру получить статус отправленного запроса на бронирование денежных средств.

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

Шаги

1. При авторизации пользователя партнера передать в scope сервис CASH_HOLD.

2. Отправить GET-запрос (/v1/cash-hold/hold/{externalId}/state), с access token пользователя партнера. Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token полученный через SSO. Пример: Bearer ecb592fe-ee3a-4ef7-9f89-5bae22f4da10-1
Параметры запроса
externalId (String) Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: application/json' --header '
Authorization: Bearer ecb592fe-ee3a-4ef7-9f89-5bae22f4da10-1'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/cash-hold/hold/1550ff04-07d6-427b-8c25-27484e8cc830/state'

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

Наименование Описание
DocState {
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional) Статус документа,
actualHoldAmount (number, optional) Cумма забронированных денежных средств (рассчитывается с учетом денежных средств, с которых сняли бронирование)
}

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

DocState {
"bankStatus": "DELIVERED",
"bankComment": null,
"actualHoldAmount": null
}

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

Код состояние документа Наименование статуса Назначение кода состояния
Промежуточные статусы/Продолжать опрашивать
ACCEPTED Принят Электронный документ принят на стороне Банка
ACCEPTED_BY_ABS Принят АБС Электронный документ был принят к обработке в АБС Банка
CREATED Создан Документ записан в БД, проверки не выполнялись
DELIVERED Доставлен Запрос доставлен в ДБО и взят в обработку
EXPORTED Выгружен Электронный документ выгружен Банком в АБС
FUNDS_FULLY_HELD Средства полностью заблокированы Средства полностью забронированы на счете клиента
FUNDS_PARTLY_UNHELD Средства частично разблокированы Средства частично разбронированы на счете клиента
SIGNED Подписан ЭД подписан предусмотренным для него комплектом подписей.
Окончательные статусы/Прекратить опрос
CHECKERROR Ошибка контроля ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
DENIED Отказан Электронный документ отказан банком
INVALIDEDS ЭП/АСП не верна Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
REQUISITEERROR Ошибка реквизитов В ЭД указаны ошибочные реквизиты
REFUSEDBYABS Отказан АБС ЭД не прошел проверки в АБС.
Окончательные(Успешные) статусы/Прекратить опрос
FUNDS_FULLY_UNHELD Средства полностью разблокированы Средства полностью разбронированы на счете клиента

Отмена бронирования средств на счете

Ресурс /v1/cash-hold/unhold позволяет Партнеру отправить запрос на отмену бронирования денежных средств на счете клиента при отмене предоставления услуг.

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

Шаги

1. При авторизации пользователя партнера передать в scope сервис CASH_HOLD.

2. Отправить POST-запрос (/v1/cash-hold/unhold), с access token пользователя партнера. Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
CashUnholdRequest {
amount (number) Сумма разблокировки ,
bankComment (string, optional, read only) Банковский комментарий к статусу документа ,
bankStatus (string, optional, read only) Статус документа ,
cashHoldExternalId (string) Идентификатор связанного запроса на бронирование, присвоенный партнёром (UUID) ,
digestSignatures (Array[Signature]) Электронные подписи по дайджесту документа ,
externalId (string) Идентификатор документа, присвоенный партнёром (UUID) ,
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "cashHoldExternalId":"091de1f5-f40b-4d11-92c7-b284f1a8b6cd",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}

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

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

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

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

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

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

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

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

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

Наименование поля Описание поля
amount Сумма бронирования
cashHoldExternalId Идентификатор запроса на бронирование, присвоенный партнером
externalId Идентификатор запроса на бронирование, присвоенный партнером

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

amount=100.00
cashHoldExternalId=091de1f5-f40b-4d11-92c7-b284f1a8b6cd
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

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

Ресурс /v1/cash-hold/unhold/{externalId}/state позволяет получить статус обработки запроса отмены бронирования денежных средств на счете клиента.

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

Шаги

1. При авторизации пользователя партнера передать в scope сервис CASH_HOLD.

2. Отправить GET-запрос (/v1/cash-hold/unhold/{externalId}/state), с access token пользователя партнера. Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token полученный через SSO
Пример: Bearer ecb592fe-ee3a-4ef7-9f89-5bae22f4da10-1
Параметры запроса
externalId (String) Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: application/json' --header '
Authorization: Bearer ecb592fe-ee3a-4ef7-9f89-5bae22f4da10-1' 
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/cash-hold/unhold/1550ff04-07d6-427b-8c25-27484e8cc830/state'

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

Наименование Описание
DocState {
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional) Статус документа,
actualHoldAmount (number, optional) Cумма забронированных денежных средств (рассчитывается с учетом денежных средств, с которых сняли бронирование)
}

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

DocState {
"bankStatus": "DELIVERED",
"bankComment": null,
"actualHoldAmount": null
}

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

Код состояние документа Наименование статуса Назначение кода состояния
Промежуточные статусы/Продолжать опрашивать
ACCEPTED Принят Электронный документ принят на стороне Банка
ACCEPTED_BY_ABS Принят АБС Электронный документ был принят к обработке в АБС Банка
CREATED Создан Документ записан в БД, проверки не выполнялись
DELIVERED Доставлен Запрос доставлен в ДБО и взят в обработку
EXPORTED Выгружен Электронный документ выгружен Банком в АБС
SIGNED Подписан ЭД подписан предусмотренным для него комплектом подписей.
Окончательные статусы/Прекратить опрос
CHECKERROR Ошибка контроля ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
DENIED Отказан Электронный документ отказан банком
INVALIDEDS ЭП/АСП не верна Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
REQUISITEERROR Ошибка реквизитов В ЭД указаны ошибочные реквизиты
REFUSEDBYABS Отказан АБС ЭД не прошел проверки в АБС.
Окончательные(Успешные) статусы/Прекратить опрос
PROCESSED Выполнен Запрос на бронирование денежных средств выполнен.

Перевод забронированных средств

Ресурс /v1/cash-hold/unhold-transfer позволяет выполнить перевод ранее забронированных денежных средств со счета клиента на счет своей организации.

Для перевода забронированных средств необходимо отправить POST-запрос (/v1/cash-hold/unhold-transfer), в котором передать авторизационный токен (Access Token). Ключ безопасности передается в параметре Authorization заголовка запроса.

Шаги

1. При авторизации пользователя партнера передать в scope сервис CASH_HOLD.

2. Отправить POST-запрос (/v1/cash-hold/unhold-transfer). Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
CashUnholdTransferRequest {
amount (number) Сумма разблокировки ,
bankComment (string, optional, read only) Банковский комментарий к статусу документа ,
bankStatus (string, optional, read only) Статус документа ,
cashHoldExternalId (string) Идентификатор связанного запроса на бронирование, присвоенный партнёром (UUID) ,
digestSignatures (Array[Signature]) Электронные подписи по дайджесту документа ,
externalId (string) Идентификатор документа, присвоенный партнёром (UUID) ,
purpose (string) Назначение платежа,
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "cashHoldExternalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f7",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "purpose":"Оплата заказа №123. НДС нет."
}

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

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

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

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

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

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

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

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

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

Наименование поля Описание поля
amount Сумма бронирования
cashHoldExternalId Идентификатор запроса на бронирование, присвоенный партнером
externalId Идентификатор запроса на бронирование, присвоенный партнером
purpose Назначение платежа

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

amount=100.00
cashHoldExternalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f7
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
purpose=Запрос на бронирование

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

Ресурс /v1/cash-hold/unhold-transfer/{externalId}/state позволяет получить статус обработки запроса на перевод забронированных денежных средств.

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

Шаги

1. При авторизации пользователя партнера передать в scope сервис CASH_HOLD.

2. Отправить GET-запрос (/v1/cash-hold/unhold-transfer/{externalId}/state). Access token передается в параметре Authorization заголовка запроса.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token полученный через SSO
Пример: Bearer c4ae03a0-5efe-4c00-a31c-c77d08dd97bd-1
Параметры запроса
externalId (String) Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer c4ae03a0-5efe-4c00-a31c-c77d08dd97bd-1'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/cash-hold/unhold-transfer/53f343bd-4aec-4e07-9156-86863e744654/state'

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

Наименование Описание
DocState {
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional) Статус документа,
actualHoldAmount (number, optional) Cумма забронированных денежных средств (рассчитывается с учетом денежных средств, с которых сняли бронирование)
}

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

DocState {
"bankStatus": "DELIVERED",
"bankComment": null,
"actualHoldAmount": null
}

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

Код состояние документа Наименование статуса Назначение кода состояния
Промежуточные статусы/Продолжать опрашивать
ACCEPTED Принят Электронный документ принят на стороне Банка
ACCEPTED_BY_ABS Принят АБС Электронный документ был принят к обработке в АБС Банка
CREATED Создан Документ записан в БД, проверки не выполнялись
CARD2 Документ передан в картотеку Документ передан в картотеку
DELIVERED Доставлен Запрос доставлен в ДБО и взят в обработку
EXPORTED Выгружен Электронный документ выгружен Банком в АБС
SIGNED Подписан ЭД подписан предусмотренным для него комплектом подписей.
Окончательные статусы/Прекратить опрос
CHECKERROR Ошибка контроля ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
DENIED Отказан Электронный документ отказан банком
INVALIDEDS ЭП/АСП не верна Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
REQUISITEERROR Ошибка реквизитов В ЭД указаны ошибочные реквизиты
REFUSEDBYABS Отказан АБС ЭД не прошел проверки в АБС.
Окончательные(Успешные) статусы/Прекратить опрос
PROCESSED Выполнен Запрос на бронирование денежных средств выполнен.

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

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

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

  • Если блок 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 рублей.

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

Код возврата Описание кода возврата Причина возникновения
201 (POST-запрос) CREATED
Создан
202 (POST-запрос) SC_ACEPTED
Операция не завершена полностью Документ создан, сохранён но не подписан Банком
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
Внутренняя ошибка сервера