ym88659208ym87991671
Создание и отправка в Банк B2B/B2P-перевода с бизнес-карты | Документация для разработчиков

Создание и отправка в Банк B2B/B2P-перевода с бизнес-карты

Обновлено 20 декабря 2023

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

  • Текущий тестовый контур https://edupirfintech.sberbank.ru:9443

  • Новый тестовый контур https://iftfintech.testsbi.sberbank.ru:9443

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

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

Сервисы переводов Sber API позволяют запрашивать расчет комиссии за перевод, отправлять заявление на перевод, а также запрашивать статус этого заявления.

В заявлении на перевод должны указываться: карта отправителя, карта получателя, сумма перевода, размер комиссии, назначение перевода, а также внешний идентификатор заявления на перевод.

Карта отправителя должна указываться в виде идентификатора. Идентификаторы бизнес-карт организации можно получить в ответе на запрос получения списка бизнес-карт организации GET /v1/business-cards (поле businessCardId).


Перевод по номеру картыОтправитель перевода
Вид картыДебетовая бизнес-карта ПАО Сбербанк
Валюта переводаРубли РФ
ГеографияТрансграничные переводы запрещены
Платежная системаVISA, Mastercard, МИР

В зависимости от типа перевода (перевод B2B или B2C) карта получателя может быть указана разными способами. Номер карты и номер телефона отдельным письмом направляет поддержка supportdbo2@sberbank.ru на адрес электронной почты. Номер карты и номер телефона являются синтетическими данными, которые создает поддержка под определенный client ID.


Переводы B2C

Переводы с бизнес-карт Сбера физическому лицу могут осуществляться с помощью:

  • Указания номера карты получателя (любая карта ПАО Сбербанк и других банков-эмитентов РФ). В этом случае в заявлении на перевод заполняется поле receiverCardNumber, а receiverPhoneNumber не заполняется;

  • Указания номера телефона получателя (карта ФЛ ПАО Сбербанк). В этом случае в заявлении на перевод должно заполняться поле receiverPhoneNumber (формат заполнения поля: 79000000000), а receiverCardNumber не заполняется.


Переводы B2B

В случае перевода с бизнес-карты Сбера юридическому лицу перевод осуществляется только с указанием номера карты получателя (любая карта ПАО Сбербанк и других банков-эмитентов РФ). В заявлении на перевод заполняется поле receiverCardNumber, а receiverPhoneNumber не заполняется.

Заполнение поля receiverCardNumber

В поле receiverCardNumber не допускается передача номера карты получателя в открытом виде, значение номера карты должно быть обязательно зашифровано. Номер карты перед шифрованием не должен содержать пробелов и спецсимволов. Получившуюся строку необходимо зашифровать, используя алгоритм RSA шифрования "RSA/OAEP" с ключом длиной 2048.

Пример:

Строка перед шифрованием - 0000000000000000

Зашифрованная строка - HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT

Список открытых ключей для шифрования номера бизнес-карты по алгоритму RSA/ECB/OAEPWithSHA-1AndMGF1Padding

СтендСертификат rsa для шифрования бизнес-карт
Текущий тестовый контур: https://edupir.testsbi.sberbank.ru:9443Скачать
Новый тестовый контур: https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443Скачать
Пром контур: https://sbi.sberbank.ru:9443Скачать

Перевод между бизнес-картами должен осуществляться в несколько этапов:

  1. Запросить значение комиссии за перевод.
  2. Отправить заявление на перевод, указав значение комиссии из предыдущего шага.
  3. Опрашивать статус заявления на перевод до получения конечного статуса.

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

Ресурс /v1/business-cards/transfer/commission позволяет получать актуальный размер комиссии за перевод между бизнес-картами. Значение комиссии, которое возвращается в ответе на запрос, должно использоваться далее при формировании заявления на перевод между бизнес-картами.

Шаги

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

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

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
amount (number)Сумма перевода в рублях
Пример: 250.00
receiverCardNumber (string)Зашифрованный номер карты получателя
Пример: HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT
receiverPhoneNumber (string)Номер телефона получателя
Пример: 79880098877
senderBusinessCardId (string)ID карты отправителя
Пример: f8ad3141-b7e8-4924-92de-3de4fd0a464e-1

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

{
"amount": 25.00,
"receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22"
}

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

НаименованиеОписание
BusinessCardCommissionResponse
amount (number)Сумма перевода в рублях
bankComment (string, optional, read only)Комментарий
bankStatus (string)Статус запроса
commission (number, read only)Размер комиссии в рублях
receiverCardNumber (string)Зашифрованный номер карты получателя
receiverFullName (string)ФИО получателя
receiverPhoneNumber (string)Номер телефона получателя
senderBusinessCardId (string)ID карты отправителя

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

{
"amount": 25.00,
"bankComment": "Некорректный размер комиссии",
"bankStatus": "OK",
"commission": 3.00,
"receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"receiverFullName": "ИЛЬЯ ЛЕОНИДОВИЧ Е."
"senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22"
}

Отправка заявления на перевод между бизнес-картами

Ресурс /v1/business-cards/transfer позволяет создавать документ «Заявление на перевод между бизнес-картами» как в виде черновика, так и в виде документа, заверенного ЭП.

Шаги

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

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

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

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

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
amount (number)Сумма перевода в рублях
Пример: 250.00
commission (number)Размер комиссии в рублях
Пример: 1.00
Signature
base64Encoded (string)Значение электронной подписи, закодированное в Base64
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
externalId (string)Внешний идентификатор заявления на перевод
Пример: 31663ef5-7975-4016-b0f3-f1d70a4e9c22
purpose (string)Назначение перевода
receiverCardNumber (string)Зашифрованный номер карты получателя
Пример: HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT
receiverPhoneNumber (string)Номер телефона получателя
Пример: 79880098877
senderBusinessCardId (string)ID карты отправителя
Пример: 31663ef5-7975-4016-b0f3-f1d70a4e9c22

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

{
"amount": 25.00,
"commission": 2.00,
"digestSignatures": [{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId": "f8ad3141-b7e8-4924-92de-3de4fd0a464e",
"purpose": "Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС",
"receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22"
}

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

НаименованиеОписание
BusinessCardTransferResponse
amount (number)Сумма перевода в рублях
bankComment (string, optional, read only)Банковский комментарий к статусу документа
bankStatus (string)Статус документа
commission (number, read only)Размер комиссии в рублях
Signature
base64Encoded (string)Значение электронной подписи, закодированное в Base64
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
externalId (string)Внешний идентификатор заявления на перевод
purpose (string)Назначение перевода
receiverCardNumber (string)Зашифрованный номер карты получателя
receiverFullName (string)ФИО получателя
receiverPhoneNumber (string)Номер телефона получателя
senderBusinessCardId (string)ID карты отправителя

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

{
"amount": 25.00,
"bankComment": "string",
"bankStatus": "DELIVERED",
"commission": 2.00,
"digestSignatures": [{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId": "f8ad3141-b7e8-4924-92de-3de4fd0a464e",
"purpose": "Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС",
"receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"receiverFullName": "СЕРГЕЙ ВАСИЛЬЕВИЧ А.",
"senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22"
}

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

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

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

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

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

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

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

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

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

С дополнительной информацией можно ознакомиться в инструкции.

Алгоритм сортировки дайджеста

В дайджесте в соответствии с запросом должно быть указано либо поле receiverCardNumber, либо поле receiverPhoneNumber.

  1. Поля дайджеста должны быть отсортированы по алфавиту.

  2. Значения суммы платежа и комиссии должны задаваться с точностью 2-х знаков после запятой.

  3. Разделитель строк должен быть в формате unix (одиночный \n).

  4. Последняя строка дайджеста не должна содержать перевод строки.

  5. В назначении платежа допустимо использовать определенные символы, а перевод строк должен быть экранирован как \\n.

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

Наименование поляОписание поляПример
amountРазмер перевода25.00
commissionРазмер комиссии2.00
externalIdВнешний идентификатор документаf8ad3141-b7e8-4924-92de-3de4fd0a464e
purposeНазначение переводаИванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС
receiverCardNumberЗашифрованный номер карты получателяHlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep
receiverPhoneNumberНомер телефона получателя79880098877
senderBusinessCardIdID карты отправителя бизнес-карты31663ef5-7975-4016-b0f3-f1d70a4e9c22

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

amount=25.00
commission=2.00
externalId=f8ad3141-b7e8-4924-92de-3de4fd0a464e
purpose=Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС
receiverCardNumber=HlaeIHXXEcGT1bFxo1NlpAzpr
receiverPhoneNumber=79880098877
senderBusinessCardId=31663ef5-7975-4016-b0f3-f1d70a4e9c22

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

Ресурс /v1/business-cards/transfer/{externalId}/state позволяет получить статус ранее отправленного заявления на перевод между бизнес-картами.

Шаги

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

2. Получить externalId.

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

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
externalId (number)Внешний идентификатор документа
Пример: 550e8400-e29b-41d4-a716-446655440000

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

curl -X GET --header 'Accept: /' --header 
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/business-cards/transfer/550e8400-e29b-41d4-a716-446655440000/state'

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

НаименованиеОписание
BusinessCardTransferResponse
bankComment (string)Банковский комментарий к статусу документа
Пример: null
bankStatus (string)Статус документа
Пример: CREATED
channelInfo (string)Комментарий, специфичный для документа, полученного по данному каналу
Пример: null

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

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

Пример неуспешного ответа

{
"cause": "WORKFLOW_FAULT",
"referenceId": "55317e3b-83d2-4273-8656-8efca8ac8c22",
"message": "При запросе на получении комиссии возникла ошибка {Error: Операция в данный момент недоступна, попробуйте повторить позднее.; 804}",
"checks": [],
"fieldNames": null
}

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

Код состояние документаНаименование статуса
Промежуточный/Продолжать опрашивать
ACCEPTEDПринят
CREATEDСоздан
DELIVEREDДоставлен
EXPORTEDВыгружен
ACCEPTED_BY_ABSПринят АБС
FRAUDSMSТребуется подтверждение СМС паролем
FRAUDREVIEWНа проверке у специалиста банка
FRAUDALLOWОдобрен ФРОД
Окончательный/Прекратить опрос
CHECKERRORОшибка контроля
FRAUDDENYОтвергнут ФРОД
INVALIDEDSЭП/АСП не верна
REFUSEDBYBANKОтказано Банком
REFUSEDBYABSОтказан АБС
REQUISITEERRORОшибка реквизитов
Окончательный(Успешный)/Прекратить опрос
PROCESSEDИсполнен
IMPLEMENTEDИсполнен

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

Код возвратаОписание кода возвратаПричина возникновения
200OK
Успешный код возврата
201CREATED
Документ создан
400DESERIALIZATION_FAULT
Неверный формат запросаНеверный формат запроса.
WORKFLOW_FAULT
Ошибка расчета комиссии, операция отклонена. Обратитесь к агрегаторуПроверка полученной комиссии от Платформы на минимально возможную не пройдена.
Операция отклонена. Обратитесь к агрегаторуРазмер выставленной суммы комиссии за перевод равен "0" или равен = меньше установленной суммы.
Карта с идентификатором хххххххх-хххх-хххх-хххх-хххххххххххх недоступна для внешнего сервиса
Не указан номер документа
Номер документа длиннее допустимого
Номер документа не должен содержать пробелы
Номер документа содержит недопустимые символы
Номер документа не может быть равен нулю
Некорректно заполнена дата документа
Некорректный номер карты списания
Карта списания не найдена
Карта списания неактивна
Перевод невозможен, данные держателя карты не совпадают с данными вашей учетной записи
Не указана сумма перевода
В документе указана нулевая или отрицательная сумма
Не установлен лимит на транзакцию для перевода с карты на карту
Сумма перевода превышает лимит на транзакцию для перевода с карты на карту
Некорректный номер карты зачисления
Для карты зачисления указан тот же счет, что и у карты списания
Наличие комплаенс-блокировки
В поле "${fieldName}" необходимо указать 11 цифр
Карта с идентификатором хххххххх-хххх-хххх-хххх-хххххххххххх недоступна для внешнего сервиса
Возникли проблемы с картой получателя
Карта зачисления не является картой Сбербанка
Недостаточно средств
Операция в данный момент недоступна, попробуйте повторить позднее
Операция недоступна для выбранной карты
Перевод не может быть выполнен. Превышен лимит по карте
Перевод не может быть выполнен. Проверьте номер карты получателя
Пожалуйста, для проверки карты отправителя обратитесь в контактный центр Банка по телефону 8-800-5555-777, с моб. 0321
Пожалуйста, обратитесь в контактный центр Банка для проверки карты
Некорректный формат запроса. Обратитесь в службу технической поддержки
Нет доступа к сервису, либо некорректный сертификат. Обратитесь в службу технической поддержки.
VALIDATION_FAULT
Ошибка валидацииОшибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
401UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан некорректный или просроченный access_token.
403ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещенУ пользователя нет прав на использование соответствующего сервиса Sber API (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404NOT_FOUND
Ресурс не найден
CARD_ID_NOT_FOUND
Бизнес-карта с указанным ID не найденаНевозможно найти бизнес-карту отправителя с указанным внешним идентификатором.
500UNKNOWN_EXCEPTION
Внутренняя ошибка сервераВнутренняя ошибка сервера
503UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступенПроводятся технические работы
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.