Подписки

Сценарий

1. Получить AccessToken
2. Получить сведения о клиентах подключенных к подпискам и пакетам услуг
3. Отправить информацию по тарифу за используемый клиентом сервис (опционально)
4. Реализовать один из вариантов списаний с клиента: 4.1 Платежное требование с электронной подписью 4.2 Начисления

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

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

Клиенты с подключенными подписками

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

Шаги

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

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

Для получения информации о клиентах, подключенных к подпискам и пакетам услуг, необходимо отправить GET-запрос (/v1/partner-info/advance-acceptances), в котором необходимо передать авторизационный токен (Access Token), полученный для собственной организации, дату, за которую запрашивается информация (date). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

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

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'

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

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

{
   "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/partner-info/package-of-services позволяет Партнеру получить сведения о клиентах, подключенных к пакетам услуг с небанковскими сервисами.

Шаги

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

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

Для получения документа необходимо отправить GET-запрос (/v1/partner-info/package-of-services), в котором передать авторизационный токен (Access Token) и дату (подключения/отключения/изменения статуса ПУ). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

curl -X GET --header 'Accept: application/json' --header

'Authorization:  Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/partner-info/package-of-services?date=2018-09-12'

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

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

{
   "Inn":"7733812920",
   "orgName":"Общество с ограниченной ответственностью Ромашка",
   "orgIdHash":"31256b9025db931f02f2353213061d46f309ba09fc5464cb4c14c2f69abf7024",
   "bundles":[
      {
         "code":"POLNHODB",
         "name":"Полным ходом",
         "sinceDate":"2018-12-31",
         "untilDate":"2019-12-31",
         "currentState":"ACTIVE"
      }
   ]
}

Информация по тарифам сервисов

Ресурс /v1/client-tariffs позволяет Партнеру передать в банк информацию по тарифу за использование сервиса/услуги клиентом.

Шаги

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

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

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

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

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

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

curl -X GET --header 'Accept: application/json' --header

'Authorization:  Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/client-tariffs'

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

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

{
   "activationDate":"2018-12-31",
   "code":"N",
   "description":"Описание тарифа N",
   "expireDate":"2018-12-31",
   "expireTrialModeDate":"2018-12-31",
   "name":"Тариф N",
   "plannedPaymentDate":"2018-12-31",
   "rateAmount":1.01,
   "ratePeriodMonths":12,
   "tokenUrl":"https://www.partner.ru/tariffs",
   "trialMode":true,
   "url":"https://www.partner.ru/tariffs",
   "useAdditionalTariff":true
}

Если billing выполняется по каждому пользователю, то в поле rateAmount необходимо указывать общую сумму списания в рамках организации.

Информация по офертам клиента

Ресурс /v1/partner-info/offers позволяет Партнеру получить информацию по офертам клиента, которые были заключены пользователями этого клиента.

Шаги

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

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

Для получения информации по офертам клиента, которые были заключены пользователями этого клиента с Партнером, необходимо отправить GET-запрос (/v1/partner-info/offers), в котором необходимо передать авторизационный токен (Access Token), полученный для собственной организации, хэш от идентификатора организации клиента (client), и статус запрашиваемых оферт (status). Авторизационный токен передается в параметре Authorization заголовка запроса. Хэш от идентификатора организации клиента можно узнать из запроса Получение информации о клиенте (т.е. из запроса user-info (значение атрибута HashOrgId в ответе на запрос user-info) по данному клиенту). Информацию необходимо хранить на своей стороне для последующего использования.

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

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

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer c5e7110b-394a-45eb-9a4b-d8759cf6f9eb-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/partner-info/offers?client=66e018dc56ac32363f3afdc92e86c092943bba97c16986327ab2f4f6b6ce1435'

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

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

{
   "clientId":"1005",
   "inn":"7707083893",
   "orgName":"OrgName",
   "users":[
      {
         "accountList":[
            "string"
         ],
         "sinceDate":"2018-12-31",
         "status":"PUBLIC",
         "sub":"026f8e459c8f89ef75fa7a78265a0025",
         "untilDate":"2018-12-31",
         "userName":"Name"
      }
   ]
}

Таблица допустимых значений параметра status:

Если параметр status не указан в запросе, то предполагается что запрос выполняется по всем допустимым значениям параметра status.

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

Ресурс /v1/payment-requests/outgoing позволяет Партнеру создавать исходящие платёжные требования, где получателем средств является организация, предоставляющая сервис.

Шаги

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

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

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

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

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

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

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

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer c5e7110b-394a-45eb-9a4b-d8759cf6f9eb-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payment-requests/outgoing'

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

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

{
   "acceptanceTerm":"string",
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "crucialFieldsHash":"string",
   "date":"2018-12-31",
   "deliveryKind":"электронно",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "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":"string",
   "priority":"5",
   "purpose":"Оплата заказа №123. НДС нет.",
   "vat":{
      "amount":1.01,
      "rate":"7",
      "type":"NO_VAT"
   },
   "voCode":"61150"
}

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

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

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

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

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

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

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

Формат дайджеста платёжного требования

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

acceptanceTerm=5
amount=100.01
date=2018-12-31
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
operationCode=02
payeeAccount=40802810600000200000
payeeBankBic=044525225
payeeBankCorrAccount=30101810400000000225
payeeInn=0
payeeName=Общество с ограниченной ответственностью "Получатель"
payerAccount=40802810600000200000
payerBankBic=044525225
payerBankCorrAccount=30101810400000000225
payerInn=0
payerName=Общество с ограниченной ответственностью "Клиент"
paymentCondition=1
priority=5
purpose=Назначение платежа

Процесс обработки платежного требования

Обработка платежного требования (ПТ)

Выгрузка ПТ из СББОЛ осуществляется каждые 5 минут в период с 9:00 – 16:30

Если плательщик в Сбербанке

При поступлении платежного требования на стороне Банка выполняются следующие проверки:

1. Логические проверки плательщика/получателя ПТ. ПТ не исполняется и возвращается ошибка, если не прошли проверки

2. Проверка на наличие заранее данного акцепта(ЗДА), выданного клиентом в Партнеру

   2.1 Если ЗДА есть:

       2.1.1  Проверка реквизитов ЗДА
   
            2.1.1.1 Если проверка пройдена, выполняется проверка на ограничение по счету:
   
                 2.1.1.1.1 Если есть полные ограничения на списание денежных средств по счету, платежный документ помещается бессрочно в Картотеку 1
   
                 2.1.1.1.2  Если есть частичные ограничения, проверяется достаточность средств для списания (остаток от блокировки)
   
            2.1.1.2 Выполняется проверка наличия денежных средств на счете:
   
                 2.1.1.2.1  Если денежных средств достаточно на полную оплату требования (с учетом всех действующих частичных блокировок средств), сразу выполняется списание и перечисление
   
                 2.1.1.2.2 Если денежных средств недостаточно (доступна не полная сумма), документ помещается в Картотеку 1 без срока и оплачивается из нее на сумму свободных средств
   
                 2.1.1.2.3 Если денежных средств на счете нет, вся сумма помещается в Картотеку 1/ Картотеку 2
   
                 2.1.1.2.4  Если выявлено неполное соответствие ЗДА (например, не сходится одна цифра в дате или регистр в номере договора (русские/англ.буквы), документ передается на ручную обработку в операционный центр

   2.2 Если ЗДА нет или реквизиты ЗДА полностью не соответствуют реквизитам из ПТ, то платежное требование помещается на 5 рабочих дней (не считая дня поступления) в Картотеку 1 для ручного акцепта клиента

Если получатель Внешний плательщик

ПТ сформированное в СББОЛ уходит в Банк России, далее Банк России отправляет в банк получателя

Частичная оплата со стороны клиента, периодичность обработки вновь появившихся денежных средств на счете клиента

Ручной акцепт:

          Акцепт ПТ клиент может выполнить в СберБизнес. Есть возможность акцептовать как полную сумму, так и частично. После акцепта формируется документ на оплату

          При частичном акцепте суммы, оставшаяся сумма остается в картотеке до конца срока нахождения проводки в Картотеке либо на оставшуюся сумму можно сформировать отказ

Списание денежных средств по проводке в бессрочной Картотеке 2 (при наличии ЗДА):

          Списание выполняются с 9 до 22 часов каждые 2-2,5 часа. Перебираются все счета  с Картотекой 2 и Картотекой 1 без срока, определяется платежеспособность счета (рассчитывается остаток свободных средств >0) и запускается процесс списания. Если до полного списания средств недостаточно, то выполняется частичное списание

Отзыв платежного документа из Картотеки:

         ИПТ в Картотека 1 (на ручном акцепте клиента) может быть отозвано плательщиком (отказ от акцепта)

         Если ИПТ находится бессрочно в Картотека 1 или 2, отозвать ИПТ в СберБизнес нельзя

Действие ЗДА:

         ЗДА начинает действовать со дня следующего за днем поступления в Банк

         Если ПТ отправить в день создания ЗДА, платежный документ попадет в Картотеку 1 (на ручной акцепт клиенту)

Закрытие счета:

          При закрытии счета все документы в картотеке  аннулируются (возвращаются составителям без исполнения) без списания

Статус SEND_TO_PAYER

          Если платежный документ помещается в Картотеку 1 или Картотеку 2, то в статус документа переводится в ``SEND_TO_PAYER``

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

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

Шаги

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

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

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

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

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

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

curl -X GET --header "Accept: /" --header

"Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1"

"https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payment-requests/outgoing/ffffffff-fffa-458e-ad92-fff9497303ba/state"

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

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

{

"bankStatus": "CREATED",

"bankComment": null,

"channelInfo": null

}

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

Списание платы за использование сервиса

Ресурс /v1/client-accruals позволяет Партнеру отправлять в банк запрос на списание платы за использование клиентом сервиса. Изначально списание происходит на счет банка, в дальнейшем банк переводит деньги Партнеру.

Шаги

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

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

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

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

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

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

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

{
   "account":"40802810600000200000",
   "amount":1.01,
   "amountDebt":1.01,
   "amountVat":1.01,
   "bankComment":"string",
   "bankStatus":"ANNULLED",
   "clientId":1005,
   "client":"ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5",
   "countServiceFact":20,
   "dateExpiration":"2018-12-31",
   "dateSince":"2018-12-31",
   "dateUntil":"2018-12-31",
   "datetimeStatusChange":"2018-12-31T23:59:59",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "purpose":"Оплата заказа №123. НДС нет."
}

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

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

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

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

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

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

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

Формат дайджеста платёжного требования

| Наименование поля | Описание поля | | ----------------- | ------------- || | client | Идентификатор организации | | clientId | Идентификатор сервиса | | externalId | Идентификатор начисления, присвоенный партнёром (UUID) | | account | Счёт клиента для списания комиссии | | dateSince | Дата начала периода списания | | dateUntil | Дата окончания периода списания | | countServiceFact | Количество фактов потребления услуги за период | | amount | Сумма начисления без НДС | | amountVat | Сумма НДС | | purpose | Назначение платежа | | dateExpiration | Дата начала взимания пени при просрочке платежа |

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

client=ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5
clientId=1005
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
account=40802810600000200000
dateSince=2018-12-31
dateUntil=2018-12-31
countServiceFact=20
amount=1.01
amountVat=1.01
purpose=Оплата заказа №123. НДС нет.
dateExpiration=2018-12-31

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

Ресурс /v1/client-accruals/{externalId} позволяет Партнеру получить документ по списанию банком денежных средств с клиента за пользование сервисом.

Шаги

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

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

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

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

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

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

curl -X GET --header 'Accept: application/json' --header

'Authorization:  Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/client-accruals/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6'

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

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

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

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

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

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

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

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

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

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

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