Общее

Выплаты через Сбер выполняются с корпоративной карты (Sber Business Card) в рамках авторизованной сессии пользователя Сбер через личный кабинет мерчанта в разделе "Интеграции". Каждая выплата подтверждается пользователем на стороне Сбера, после чего мерчант вызывает метод подтверждения выплаты.

Base url

API методы выплат (выплаты на карту или сбп):

Production url: https://api.pay.kvell.group/v1
Stage url: https://api.pay.stage.kvell.group/v1

API справочных методов (информация о пользователе, список корпоративных карт, список банков СБП):

Production url: https://api.baas.kvell.group/v1
Stage url: https://api.baas.stage.kvell.group/v1

Заголовки запроса

Название	Тип данных	Обязательно	Описание
`X-Api-Key`	string	Да	Уникальный идентификатор магазина
`X-Signature`	string	Да	Подпись

Формирование подписи

Для методов создания выплаты используется ЭЦП, алгоритм RSA/SHA256:

Выплата на карту — POST /v1/orders/account2card/sber
Выплата СБП — POST /v1/orders/payout/sbp/sber

Мерчант на своей стороне генерирует пару ключей и передаёт публичную часть в тех-поддержку. Алгоритм формирования подписи такой же, как и при совершении выплаты на карту.

Для остальных методов подпись формируется конкатенацией параметров запроса, от полученной строки берётся sha256:

Метод	Подпись
Информация о пользователе	`sha256({X-Api-Key}{session_id}{secret_key})`
Список корпоративных карт	`sha256({X-Api-Key}{session_id}{secret_key})`
Список банков СБП	`sha256({X-Api-Key}{session_id}{secret_key})`
Проверка возможности выплаты СБП	`sha256({X-Api-Key}{phone}{bank_id}{secret_key})`
Получение статуса проверки возможности выплаты	`sha256({X-Api-Key}{request_id}{secret_key})`
Подтверждение выплаты	`sha256({X-Api-Key}{transaction}{session_id}{secret_key})`

где secret_key - секретный ключ, который находится в настройках магазина мерчанта.

Параметры сессии Сбер

Название	Тип данных	Описание
`session_id`	string	Идентификатор авторизованной сессии Сбер. Создаётся после прохождения пользователем авторизации в Сбер.
`business_card_id`	string	Идентификатор корпоративной карты, с которой выполняется выплата. Возвращается в поле `business_card_id` метода списка карт.
`user_crypto_type`	string	Криптопрофиль пользователя Сбер: `SMS` — подтверждение по СМС, `Token` — электронный ключ (токен). Возвращается в поле `user_crypto_type` метода информации о пользователе. По умолчанию `SMS`.

Порядок вызова методов

Выплата на карту:

Информация о пользователе — получить user_crypto_type по session_id.
Список корпоративных карт — выбрать карту и получить business_card_id.
Выплата на карту — создать выплату, в ответе приходит redirect_url.
Открыть redirect_url и подтвердить операцию в Сбер.
Подтверждение выплаты — обновить статус выплаты в KVELL.

Выплата СБП:

Информация о пользователе — получить user_crypto_type по session_id.
Список корпоративных карт — выбрать карту и получить business_card_id.
Список банков СБП — проверить, что банк получателя доступен для выплат через Сбер.
Проверка возможности выплаты СБП — получить request_id. Шаг необязательный.
Получение статуса проверки возможности выплаты. Шаг необязательный.
Выплата СБП — создать выплату, передав полученный request_id, в ответе приходит redirect_url.
Открыть redirect_url и подтвердить операцию в Сбер.
Подтверждение выплаты — обновить статус выплаты в KVELL.

Проверка возможности выплаты

Вызывать методы проверки возможности выплаты СБП и получения её статуса необязательно — выплату на карту или по СБП можно создавать сразу. Проверка нужна, если требуется заранее убедиться, что выплата по реквизитам получателя возможна, сверить ФИО получателя с данными НСПК или получить request_id для передачи в запросе выплаты.

Статус выплаты

Если после подтверждения выплата осталась в статусе processing, итоговый статус необходимо получить методом статуса транзакции.

Обратный редирект

Ссылка redirect_url из ответа методов создания выплаты открывается для подтверждения операции в интерфейсе СберБизнес. В redirect_url приходит ссылка без адреса возврата, поэтому параметр backUrl с адресом возврата на страницу мерчанта добавляется в конец полученной ссылки:

{redirect_url}?backUrl=https%3A%2F%2Fmerchant.example.com%2Fpayout-result

Требования Сбера к параметру:

backUrl необходимо закодировать URLEncode;
если backUrl не указать, пользователь после подписания не сможет вернуться на платформу мерчанта;

Коды ошибок

Ошибки возвращаются в теле JSON-ответа в списке errors. Ответы 5xx, таймауты и обрывы соединения обрабатываются отдельно — см. Обработка ошибок и таймаутов.

Ошибка

{
  "errors": [
    {
      "code": 20002,
      "message": "Неверная подпись"
    }
  ]
}

Код	Описание
`20001`	Неверный api-key
`20002`	Неверная подпись
`20003`	Payout профиль не привязан к магазину
`20005`	Ошибка от PSP сервиса
`20007`	Транзакция совершалась прежде
`20009`	Заказ не найден
`20015`	Недостаточно средств
`20019`	Превышен лимит выплат по магазину
`20020`	Получатель не задан
`20038`	Некорректный номер черновика
`20040`	Черновик выплаты не найден
`20041`	Итоговое поле `description` превышает допустимую длину
`20042`	Данные из выплаты и черновика выплаты не совпадают
`20098`	Ошибка валидации полей запроса