Совершение выплаты на карту

Создаёт выплату на банковскую карту по номеру карты или токену карты.

Сценарий интеграции

Сформируйте уникальный transaction и выберите способ передачи карты получателя.
Подпишите точное тело запроса и отправьте выплату.
Проверяйте состояние операции по transaction, пока не получите completed или canceled.

URL

ProductionStage

POST https://api.pay.kvell.group/v1/orders/account2card

POST https://api.pay.stage.kvell.group/v1/orders/account2card

Запрос

Заголовки

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

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

Запрос необходимо подписать электронной подписью RSA/SHA-256. Передайте результат в заголовке X-Signature.

Пошаговый алгоритм, требования к ключам, примеры для Python, PHP и OpenSSL, а также диагностика ошибки 20002 приведены в общем разделе «Формирование подписи для выплат».

Тело запроса

Параметр	Тип	Обязательно	Описание
`recipient_pan`	string	Да	Номер карты получателя без пробелов и разделителей.
`amount`	integer	Да	Сумма в копейках. Например, `15000` — 150 ₽.
`transaction`	string	Да	Уникальный идентификатор операции в системе мерчанта.
`description`	string	Да	Назначение выплаты, не более 210 символов.
`customer`	string	Нет	Идентификатор плательщика, email или номер телефона.
`extra_data`	object	Нет	Дополнительные данные мерчанта.
`fiscal_data`	object	Нет	Данные для фискализации чека по 54-ФЗ.

Работа с номером карты

recipient_pan содержит платёжные данные. Не записывайте полный номер карты в логи и не храните его без необходимости. Соблюдайте применимые требования PCI DSS.

Пример

JSON

{
  "recipient_pan": "4111111111111111",
  "amount": 15000,
  "transaction": "payout-card-20260810-0001",
  "description": "Выплата по договору 42",
  "customer": "customer@example.com"
}

Ответ

Выберите HTTP-код, чтобы посмотреть пример, параметры ответа и рекомендуемые действия.

Если HTTP-ответ не получен

Таймаут или разрыв соединения обрабатывайте так же, как ответ 5XX: результат операции неизвестен, поэтому сначала проверьте статус по исходному transaction. Не создавайте новую выплату с другим идентификатором.

2004004034044225XX

Пример ответа 200 (OK)

{
  "order": {
    "id": "3b3c19f4-c680-4f5d-bf2e-c0835439cf12",
    "status": "processing",
    "transaction": "payout-card-20260810-0001",
    "amount": 15000,
    "commission": 150,
    "description": "Выплата по договору 42",
    "additional_data": {
      "auth_code": null,
      "rrn": null
    },
    "error_code": null,
    "error_message": null,
    "created_at": "2026-08-10T09:15:27.231000+00:00"
  },
  "transaction": "payout-card-20260810-0001",
  "status": "processing"
}

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

Параметр	Тип	Описание
`order`	object	Созданная выплата.
∟ `id`	string	Идентификатор выплаты в KVELL.
∟ `status`	string	Текущий статус выплаты. Возможные значения приведены в разделе «Статусы выплаты».
∟ `transaction`	string	Идентификатор операции, переданный мерчантом.
∟ `amount`	integer	Сумма выплаты в копейках.
∟ `commission`	integer	Комиссия в копейках.
∟ `description`	string \| null	Назначение выплаты. Может включать префикс, настроенный для магазина.
∟ `additional_data`	object \| null	Дополнительные данные, полученные при обработке выплаты.
∟ `auth_code`	string \| null	Код авторизации, если его вернул банк.
∟ `rrn`	string \| null	Идентификатор банковской транзакции, который генерирует банк-эквайер.
∟ `error_code`	string \| null	Код причины отклонения. Возможные значения приведены в разделе «Коды ошибок транзакции».
∟ `error_message`	string \| null	Описание причины отклонения. Для неотклонённой выплаты возвращается `null`.
∟ `created_at`	string	Дата и время создания выплаты в формате ISO 8601.
`transaction`	string	Идентификатор операции в системе мерчанта.
`status`	string	Текущий статус выплаты; совпадает с `order.status`.

Пример ответа 400 (Bad Request)

{
  "errors": [
    {
      "code": 20019,
      "message": "Превышен лимит выплат по магазину"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. В примере — `20019`.
∟ `message`	string	Описание причины отклонения запроса.

Пример ответа 403 (Forbidden)

{
  "errors": [
    {
      "code": 20037,
      "message": "Доступ запрещен"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. Для запрета доступа — `20037`.
∟ `message`	string	Описание причины запрета доступа.

Пример ответа 404 (Not Found)

{
  "errors": [
    {
      "code": 20006,
      "message": "Магазин не найден"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. Для ненайденного магазина — `20006`.
∟ `message`	string	Описание причины, по которой ресурс не найден.

Что означает ответ

Магазин с переданным X-Api-Key не найден в выбранном контуре. Выплата не создана.

Пример ответа 422 (Unprocessable Entity)

{
  "errors": [
    {
      "code": 20020,
      "message": "Получатель не задан"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок валидации. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки.
∟ `message`	string	Причина ошибки валидации.

Пример ответа 5XX (Internal Server Error)

{
  "errors": [
    {
      "code": 20000,
      "message": "Неизвестная ошибка"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. Для неизвестной ошибки — `20000`.
∟ `message`	string	Описание технической ошибки.

5XX, таймаут и разрыв соединения

Во всех этих случаях результат запроса считается неопределённым: выплата могла быть создана, даже если клиент не получил ответ. Оставьте транзакцию в своей системе в состоянии «обрабатывается» до получения подтверждённого результата от KVELL.

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

Единый алгоритм обработки

Не помечайте выплату успешной или отклонённой только на основании технической ошибки.
Сохраните выплату у себя в состоянии «обрабатывается».
Запросите статус транзакции по исходному значению transaction.
Если транзакция найдена, проверяйте её до получения финального статуса.
Если запросы статуса продолжают завершаться ошибкой, обратитесь в поддержку и передайте transaction.

Не создавайте дублирующую выплату

Не отправляйте выплату повторно с новым transaction, пока результат исходной операции не установлен.

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

Статус	Финальный	Что делать
`new`	Нет	Запрашивать статус транзакции.
`processing`	Нет	Запрашивать статус транзакции. Не создавать новую выплату.
`completed`	Да	Выплата выполнена.
`canceled`	Да	Выплата отклонена.

Полный справочник общих статусов операций приведён в разделе «Статусы транзакции».

Подтверждение через OTP

Используется только для магазинов с включённым OTP

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

При включённом OTP вместо объекта созданной выплаты API вернёт:

{
  "order": null,
  "transaction": "payout-card-20260810-0001",
  "status": "wait_confirm"
}

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

Параметр	Тип	Описание
`order`	null	Выплата ещё не создана.
`transaction`	string	Идентификатор операции, который необходимо передать в метод подтверждения.
`status`	string	`wait_confirm` — выплата ожидает подтверждения OTP-кодом.

Что означает ответ

Запрос принят, но выплата ожидает подтверждения и ещё не перешла к обработке банком. Поэтому в ответе нет id, amount, commission и created_at.

Что делать дальше

Получить OTP-код у пользователя.
Передать transaction и OTP-код в метод подтверждения выплаты.
После подтверждения получить финальный статус.