Выплаты СБП

Метод проведения выплаты физическому лицу по номеру телефона через СБП с использованием номинального счёта Сбера.

URL

Метод: POST

Production: https://api.pay.kvell.group/v1/orders/payout/smartcontract/sbp/sber
Stage: https://api.pay.stage.kvell.group/v1/orders/payout/smartcontract/sbp/sber

Параметры запроса

Название	Тип данных	Обязательно	Описание
`transaction`	string	Да	Уникальный номер транзакции на стороне мерчанта
`amount`	integer	Да	Сумма в копейках
`description`	string	Да	Описание к транзакции
`inn`	string	Да	ИНН физического лица
`kvd`	string	Да	Код вида дохода (поле 20 платёжного поручения, см. 229-ФЗ)
`phone`	string	Да	Номер телефона получателя
`bank_bic`	string	Да	БИК банка получателя
`fio`	string	Нет	ФИО получателя
`fio_check`	boolean	Нет	Проверить соответствие ФИО и номера телефона в СБП
`validate_self_employed`	boolean	Нет	Проверить статус самозанятого перед выплатой (по умолчанию `false`)
`customer`	string	Нет	Email / телефон клиента
`extra_data`	json	Нет	Дополнительные данные
`fiscal_data`	json	Нет	Фискализация чека по 54-ФЗ

Параметр kvd

kvd — код вида дохода, поле 20 в платёжном поручении (229-ФЗ, ст. 99 ч. 1, 2; ст. 101). Заполняется при перечислении заработной платы, отпускных, премий, выплатах самозанятым и иных выплатах физическим лицам. Не заполняется, если получателем является ИП или юридическое лицо.

Значение	Описание
`1`	Размер взыскания ограничен. Заработная плата и иные доходы, в отношении которых ст. 99 229-ФЗ установлены ограничения размеров удержания
`2`	Периодические выплаты, взыскание невозможно. Периодические доходы, на которые согласно ч. 1 ст. 101 229-ФЗ не может быть обращено взыскание (за исключением доходов, указанных в ч. 2 ст. 101 229-ФЗ)
`3`	Периодические выплаты, размер взыскания не ограничен. Периодические доходы, к которым согласно ч. 2 ст. 101 229-ФЗ ограничения по взысканию не применяются
`4`	Разовые выплаты, взыскание невозможно. Единовременный доход, на который согласно ч. 1 ст. 101 229-ФЗ не может быть обращено взыскание (за исключением доходов, указанных в ч. 2 ст. 101 229-ФЗ)
`5`	Разовые выплаты, размер взыскания не ограничен. Единовременный доход, к которому согласно ч. 2 ст. 101 229-ФЗ ограничения по взысканию не применяются

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

{
  "transaction": "f4462ba6-37c5-4455-b0b2-53b179f7a25c",
  "amount": 100000,
  "description": "Выплата по договору №123",
  "inn": "771234567890",
  "kvd": "1",
  "phone": "+79001234567",
  "bank_bic": "044525225",
  "fio": "Иванов Иван Иванович",
  "fio_check": true,
  "validate_self_employed": false,
  "customer": "user@example.com"
}

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

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

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

При формировании запроса необходимо использовать ЭЦП. Используется алгоритм RSA/SHA256. Данное сообщение необходимо передавать в заголовке HTTP запроса в параметре X-Signature.

Ключ для ЭЦП

Мерчант на своей стороне генерирует ключ:
```
$ openssl genrsa -out privatekey.pem 4096
```

Получает от ключа публичную часть:

$ openssl rsa -in privatekey.pem -pubout -out publickey.pem

Публичную часть ключа необходимо отправить в тех-поддержку, которая загружает содержимое в систему. Проверка подписи мерчанта X-signature происходит при запросе. Все параметры запроса должны передаваться в том виде, в котором они подписывались. Сортировать параметры не нужно.

Внимание

Валидация подписи выполняется по фактическому телу запроса. Подписывайте ровно тот JSON, который отправите в API (без изменения порядка полей, дополнительных преобразований или пересериализации между шагами).

Примеры кода

PythonPHP

import base64
import json
import requests

from Crypto.Hash import SHA256
from Crypto.PublicKey import RSA
from Crypto.Signature import PKCS1_v1_5

x_api_key = '7d1f800c-ec7d-4597-a65f-cd7896934b5a'
secret_key = 'ddee181d-f8e8-4f3f-90bf-1d7e8f122d9a'

# порядок ключей сохраняется как в теле запроса
payload = {
    "transaction": "f4462ba6-37c5-4455-b0b2-53b179f7a25c",
    "amount": 100000,
    "description": "Выплата по договору №123",
    "inn": "771234567890",
    "kvd": "1",
    "phone": "+79001234567",
    "bank_bic": "044525225",
    "fio": "Иванов Иван Иванович",
    "fio_check": True
}

# сериализуем данные один раз и используем ту же строку для подписи и для тела запроса
data = json.dumps(payload, separators=(',', ':'))

key = RSA.importKey(open('privatekey.pem').read())
digest = SHA256.new('{}{}'.format(data, secret_key).encode('utf8'))
signer = PKCS1_v1_5.new(key)
signature = signer.sign(digest)
x_signature = base64.b64encode(signature).decode('utf-8')

response = requests.post(
    'https://api.pay.kvell.group/v1/orders/payout/smartcontract/sbp/sber',
    data=data,
    headers={
        'Content-Type': 'application/json; charset=UTF-8',
        'x-api-key': x_api_key,
        'x-signature': x_signature,
    }
)

<?php
$secret_key = 'ddee181d-f8e8-4f3f-90bf-1d7e8f122d9a';

$payload = [
    "transaction" => "f4462ba6-37c5-4455-b0b2-53b179f7a25c",
    "amount" => 100000,
    "description" => "Выплата по договору №123",
    "inn" => "771234567890",
    "kvd" => "1",
    "phone" => "+79001234567",
    "bank_bic" => "044525225",
    "fio" => "Иванов Иван Иванович",
    "fio_check" => true,
];

// сериализуем данные один раз и используем ту же строку для подписи и для тела запроса
$data = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$digest = $data . $secret_key;

$key = openssl_pkey_get_private(file_get_contents('privatekey.pem'));

$signature = "";

openssl_sign($digest, $signature, $key, "sha256WithRSAEncryption");

$x_signature = base64_encode($signature);

print("x-signature: " . $x_signature . "\n");

?>

Ответ запроса

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

200: OK422: Validation error5XX: Ошибка

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "processing",
  "transaction": "f4462ba6-37c5-4455-b0b2-53b179f7a25c",
  "amount": 100000,
  "commission": 0,
  "description": "Выплата по договору №123",
  "additional_data": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2024-01-15T10:30:00"
}

{
  "errors": [
    {
      "message": "string",
      "code": 0
    }
  ]
}

Если получен ответ со статусом 5XX, транзакцию необходимо оставить в обработке и отправить запрос на метод получения статуса транзакции.
Данные ошибки могут возникнуть по различным причинам: на стороне взаимодействия сети, технических сбоев сервера или ПО.
В случае повторного возникновения данной проблемы рекомендуется обратиться в службу поддержки.

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

Название	Тип данных	Описание
`id`	string	ID платежа в системе
`status`	string	Статус транзакции
`transaction`	string	Уникальный номер транзакции на стороне мерчанта
`amount`	integer	Сумма в копейках
`commission`	integer	Комиссия в копейках
`description`	string	Описание к транзакции
`additional_data`	json	Дополнительные данные (код авторизации, RRN)
`error_code`	string	Код ошибки (при наличии)
`error_message`	string	Сообщение об ошибке (при наличии)
`created_at`	string	Дата создания транзакции

Список статусов

Название	Описание
`new`	Новая транзакция
`processing`	Транзакция обрабатывается
`canceled`	Транзакция отклонена
`completed`	Транзакция выполнена

Коды ошибок

Код	Описание
`20001`	Неверный API-ключ
`20002`	Неверная подпись
`20003`	Payout профиль не привязан к магазину
`20005`	Ошибка от платёжного сервиса
`20007`	Транзакция с таким номером уже существует
`20019`	Превышен лимит выплат по магазину
`20039`	Sber профиль не привязан к магазину
`20098`	Ошибка валидации полей запроса