Перейти к содержанию

Выплаты по реквизитам

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

URL

Метод: POST

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

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

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

Объект tax

Передаётся при налоговом платеже в пользу ФНС.

Название
 Тип данных Обязательно Описание
taxPayerInn string Да ИНН самозанятого (налогоплательщика), 12 цифр
tax_101 string Да Статус составителя расчётного документа (поле 101), 2 цифры. Пример: 01
tax_104 string Да Код бюджетной классификации КБК (поле 104), 20 цифр. Пример: 18201061201010000510
tax_105 string Да Код ОКТМО (поле 105), до 8 цифр. Пример: 60701000
tax_106 string Нет Основание налогового платежа (поле 106), 2 заглавные буквы или 0. Пример: ТП
tax_107 string Нет Налоговый период (поле 107). Форматы: МС.03.2025, КВ.02.2025, ПЛ.02.2025, ГД.00.2025
tax_108 string Нет Номер налогового документа (поле 108), до 15 символов. Пример: ТР41797
tax_109 string Нет Дата налогового документа (поле 109), формат: YYYY-MM-DD. Пример: 2025-04-15
tax_uin string Нет Уникальный идентификатор налогового платежа (УИН), 4–25 цифр

Параметр 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",
  "fio": "Иванов Иван Иванович",
  "inn": "771234567890",
  "kvd": "1",
  "account": {
    "account_number": "40817810099910004312",
    "bank_bic": "044525225",
    "bank_cor_account": "30101810400000000225",
    "bank_name": "ПАО Сбербанк"
  },
  "snils": "123-456-789 01",
  "validate_self_employed": false,
  "customer": "user@example.com"
}

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

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

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

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

Ключ для ЭЦП

  1. Мерчант на своей стороне генерирует ключ: 
    $ openssl genrsa -out privatekey.pem 4096
  2. Получает от ключа публичную часть: 
    $ openssl rsa -in privatekey.pem -pubout -out publickey.pem
  3. Публичную часть ключа необходимо отправить в тех-поддержку, которая загружает содержимое в систему. Проверка подписи мерчанта X-signature происходит при запросе. Все параметры запроса должны передаваться в том виде, в котором они подписывались. Сортировать параметры не нужно.

Внимание

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

Примеры кода

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",
    "fio": "Иванов Иван Иванович",
    "inn": "771234567890",
    "kvd": "1",
    "account": {
        "account_number": "40817810099910004312",
        "bank_bic": "044525225",
        "bank_cor_account": "30101810400000000225",
        "bank_name": "ПАО Сбербанк"
    }
}

# сериализуем данные один раз и используем ту же строку для подписи и для тела запроса
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/fl/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",
    "fio" => "Иванов Иван Иванович",
    "inn" => "771234567890",
    "kvd" => "1",
    "account" => [
        "account_number" => "40817810099910004312",
        "bank_bic" => "044525225",
        "bank_cor_account" => "30101810400000000225",
        "bank_name" => "ПАО Сбербанк",
    ],
];

// сериализуем данные один раз и используем ту же строку для подписи и для тела запроса
$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");

?>

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

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

{
  "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 Ошибка валидации полей запроса