Подтверждение выплаты на карту

Подтверждает OTP-кодом выплату на карту, для которой метод создания вернул status: wait_confirm. Метод используется только для магазинов с включённым подтверждением выплат через OTP.

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

Получите transaction из ответа метода совершения выплаты.
Получите OTP-код по настроенному для магазина каналу: SMS или email.
Подпишите точное JSON-тело и отправьте transaction вместе с OTP-кодом.
Если выплата перешла в new или processing, опрашивайте метод статуса транзакции с интервалом 2 минуты или используйте колбэк до получения финального статуса.

Срок действия OTP-кода

По умолчанию OTP-код действует 15 минут с момента генерации. Фактический срок может зависеть от настроек магазина. После истечения срока подтверждение с этим кодом завершится ошибкой.

Отличие от подтверждения СБП-выплаты

Тело запроса, схема ответа и формирование подписи совпадают с подтверждением выплаты через СБП. Отличается URL: для карточной выплаты используется /v1/orders/account2card/confirm.

URL

ProductionStage

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

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

Запрос

Заголовки

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

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

Запрос подписывается тем же алгоритмом RSA/SHA-256, что и создание карточной или СБП-выплаты. Пошаговый алгоритм приведён в общем разделе «Формирование подписи для выплат».

Тело запроса

Параметр	Тип	Обязательно	Описание
`transaction`	string	Да	Идентификатор операции из ответа метода совершения выплаты.
`otp`	string	Да	Одноразовый код подтверждения. Числовое значение можно передать строкой или числом.

Пример

JSON

{
  "transaction": "payout-card-20260810-0001",
  "otp": "123456"
}

Ответ

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

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

Результат подтверждения неизвестен: выплата могла быть создана. Не отправляйте новую выплату и не запрашивайте новый OTP-код, пока не проверите статус по исходному transaction.

2004004034044225XX

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

{
  "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"
}

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

Параметр	Тип	Описание
`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.

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

OTP-код принят, выплата создана. HTTP-код 200 не означает, что выплата завершена успешно: бизнес-результат определяется полем status.

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

{
  "errors": [
    {
      "code": 20004,
      "message": "Сессия не найдена"
    }
  ]
}

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

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

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

Код 20004 означает, что данные выплаты для указанного transaction не найдены или больше недоступны. Выплата на этом шаге не создана.

Пример ответа 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	Описание причины, по которой ресурс не найден.

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

{
  "errors": [
    {
      "code": 20098,
      "message": "otp: Field required"
    }
  ]
}

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

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

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

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

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

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

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

Результат подтверждения неизвестен: выплата могла быть создана и передана в обработку.

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

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