Получение статуса транзакции

Возвращает текущий статус и подробную информацию о платеже или выплате по идентификатору transaction в системе мерчанта. Метод не изменяет состояние операции.

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

Сохраните transaction, переданный при создании операции.
Сформируйте подпись из X-Api-Key, transaction и secret_key.
Отправьте запрос статуса с тем же X-Api-Key, с которым создавалась операция.
Если получен new или processing, получайте финальный статус одним из способов: опрашивайте метод с интервалом 2 минуты или используйте колбэк, который KVELL отправит после завершения операции.
Для canceled используйте error_code и error_message, чтобы определить причину отклонения.

Когда запрашивать статус

Используйте метод после создания операции, пока она находится в обработке. Запрос статуса также обязателен, если при создании операции получен 5XX, произошёл таймаут или разрыв соединения.

Если 5XX, таймаут или разрыв соединения произошли при запросе статуса, повторите тот же запрос с исходным transaction. Эти ошибки не определяют результат операции — дождитесь ответа 200 и проверьте поле status.

URL

ProductionStage

GET https://api.pay.kvell.group/v1/orders/{transaction}

GET https://api.pay.stage.kvell.group/v1/orders/{transaction}

Запрос

Path-параметры

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

Заголовки

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

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

Объедините X-Api-Key, transaction и secret_key без разделителей, вычислите SHA-256 от полученной строки в кодировке UTF-8 и передайте хеш в нижнем регистре в заголовке X-Signature.

SHA256(X-Api-Key + transaction + secret_key)

secret_key находится в настройках магазина. Порядок значений изменять нельзя.

Пример

cURL

curl --request GET \
  --url 'https://api.pay.kvell.group/v1/orders/payment-20260807-0001' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>'

Ответ

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

HTTP 200 — это результат запроса статуса, а не всегда успех операции

Операция найдена, но её бизнес-результат определяется полем status. Значения new и processing не являются финальными.

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

Таймаут или разрыв соединения не меняют статус транзакции и не означают её успешное или неуспешное завершение. Безопасно повторите тот же GET-запрос с исходным transaction.

2004004034044225XX

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

{
  "id": "b13e1610-f26a-4c49-84e8-0edf1650a026",
  "status": "completed",
  "transaction": "payment-20260807-0001",
  "amount": 15000,
  "commission": 150,
  "inner_commission": 50,
  "description": "Оплата заказа 42",
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail",
  "redirect_url": "https://merchant.example/success",
  "extra_data": {},
  "fiscal_data": null,
  "additional_data": {},
  "error_code": null,
  "error_message": null,
  "created_at": "2026-08-07T09:15:27.231000+00:00",
  "refund_amount": null,
  "reverse_amount": null,
  "confirm_amount": null,
  "instrument": "card",
  "ecommerce_type": "payment"
}

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

Параметр	Тип	Описание
`id`	string	Идентификатор операции в KVELL.
`status`	string	Текущий статус. Возможные значения приведены в разделе «Статусы транзакции».
`transaction`	string	Идентификатор операции в системе мерчанта.
`amount`	integer	Сумма операции в копейках.
`commission`	integer	Внешняя комиссия в копейках.
`inner_commission`	integer	Внутренняя комиссия в копейках.
`description`	string \| null	Описание операции.
`success_url`	string \| null	URL для перенаправления после успешной операции.
`fail_url`	string \| null	URL для перенаправления после неуспешной операции.
`redirect_url`	string	Итоговый URL для перенаправления пользователя. Если URL не задан в операции, возвращается адрес платёжной страницы KVELL.
`extra_data`	object	Дополнительные данные, переданные мерчантом.
`fiscal_data`	object \| null	Данные фискализации.
`additional_data`	object	Дополнительные данные, сформированные при обработке операции. Если данных нет, возвращается пустой объект `{}`.
`error_code`	string \| null	Код причины отклонения. Возможные значения приведены в разделе «Коды ошибок транзакции». Для неотклонённой операции возвращается `null`.
`error_message`	string \| null	Описание причины отклонения. Для неотклонённой операции возвращается `null`.
`created_at`	string	Дата и время создания операции в формате ISO 8601.
`refund_amount`	integer \| null	Сумма выполненных возвратов в копейках.
`reverse_amount`	integer \| null	Сумма выполненных отмен авторизации в копейках.
`confirm_amount`	integer \| null	Сумма выполненных подтверждений в копейках.
`instrument`	string \| null	Способ оплаты или выплаты. Основные значения приведены в разделе «Способы проведения операции».
`ecommerce_type`	string \| null	Тип операции. Возможные значения приведены в разделе «Типы транзакций».

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

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

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

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

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

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

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

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

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

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

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

{
  "errors": [
    {
      "code": 20009,
      "message": "Заказ не найден"
    }
  ]
}

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

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

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

Код 20009 означает, что транзакция с указанным transaction не найдена для магазина из заголовка X-Api-Key. Это ошибка поиска, а не финальный статус транзакции: ответ не содержит полей status, error_code и error_message.

Возможные причины:

в URL передан неверный transaction;
запрос отправлен с X-Api-Key другого магазина — транзакции разных магазинов изолированы;
выбран неверный контур: Production вместо Stage или наоборот;
исходный запрос завершился ошибкой до создания транзакции, например из-за валидации или неверной подписи;
статус запрошен до завершения исходного запроса на создание транзакции.

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

Проверьте transaction, X-Api-Key и выбранный контур.
Не повторяйте запрос статуса с теми же данными: пока причина не устранена, метод снова вернёт 404.
Если исходный запрос на создание ещё выполняется, сначала дождитесь его завершения.
Если создание операции завершилось успешно и идентификаторы указаны верно, обратитесь в поддержку и передайте transaction.

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

{
  "errors": [
    {
      "code": 20098,
      "message": "x-signature: Field required"
    }
  ]
}

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

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

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

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

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

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

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

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

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

Оставьте исходную операцию в текущем состоянии в своей системе.
Безопасно повторите тот же GET-запрос с исходным transaction.
Продолжайте обработку только после получения 200 и анализа поля status.
Если техническая ошибка повторяется, обратитесь в поддержку и передайте transaction.

Не создавайте новую операцию на основании технической ошибки

Ошибка метода статуса ничего не говорит о результате исходной транзакции.

Статусы транзакции

Статус	Финальный	Что означает и что делать
`new`	Нет	Транзакция создана, но обработка ещё не началась.
`processing`	Нет	Транзакция обрабатывается.
`completed`	Да	Операция выполнена успешно.
`canceled`	Да	Операция отклонена. Используйте `error_code` и `error_message` для определения причины.
`refunded`	Да	Выполнен полный возврат платежа.
`part_refunded`	Да	Выполнен частичный возврат. Текущая сумма возврата указана в `refund_amount`.
`reversed`	Да	Авторизация полностью отменена.
`part_reversed`	Да	Авторизация отменена частично. Текущая сумма отмены указана в `reverse_amount`.
`confirmed`	Да	Авторизация подтверждена полностью.
`part_confirmed`	Да	Авторизация подтверждена частично. Текущая сумма подтверждения указана в `confirm_amount`.

Типы транзакций

Значение	Описание
`payment`	Платёж.
`payout`	Выплата.
`unknown`	Тип операции не определён.
`null`	Тип отсутствует, например у ранее созданной транзакции.

Способы проведения операции

Набор значений зависит от подключённых способов оплаты и выплаты. Основные значения:

Значение	Описание
`card`	Банковская карта.
`sbp`	Система быстрых платежей.
`tpay`	T-Pay.
`alfapay`	Alfa-Pay.
`sberpay`	Sber-Pay.
`sbpb2b`	СБП B2B.
`smartcontract`	Выплата через смарт-контракт.
`sbpstaticqr`	Статический QR-код СБП.
`null`	Способ не указан, например у ранее созданной транзакции.

Дополнительные данные

Для платежа по СБП через Альфа-Банк с последующей привязкой additional_data может содержать:

Параметр	Тип	Описание
`bank_id`	string	Идентификатор банка плательщика.
`subscription_token`	string	Идентификатор привязки счёта плательщика в банке.

Коды ошибок транзакции

Поле error_code содержит причину отклонения операции при статусе canceled. Это бизнес-коды платёжных систем и банков, а не ошибки HTTP-запроса. Ошибки самого API приведены отдельно в разделе «Ошибки HTTP-ответов».

Код	Описание
`3ds-error`	Ошибка 3-D Secure авторизации
`access-denied`	Доступ запрещен
`account-restrictions`	Ограничение по карточному счету
`amount-exceeded`	Превышен лимит на сумму операции. Обратитесь в Банк
`amount-exceeds-card-ceiling`	Данная сумма превышает допустимую, и не может быть проведена с данной карты
`amount-exceeds-maximum-allowed-value`	Сумма превышает максимально допустимое значение
`amount-limit`	Транзакция отклонена по причине того, что размер платежа превысил установленные лимиты.
`an-error-occurred-during-3ds-processing`	ошибка при обработке 3DS
`authentication-failed`	Свяжитесь с вашим банком или воспользуйтесь другой картой
`authorization-declined`	В авторизации отказано. Проверьте правильность введенных данных карты или воспользуйтесь другой картой
`available-card-limit-exceeded`	Превышен доступный лимит по карте
`banned-operation`	Отказ системы противодействия мошенничеству. Операция заблокирована. Воспользуйтесь другой картой
`card-blocking`	Транзакция отклонена по причине того, что карта внесена в черный список
`card-expired`	Истек срок действия карты
`card-is-blocked`	Превышено максимальное количество попыток ввода PIN-кода. Возможно, карта заблокирована временно
`card-is-lost`	Карта утеряна
`card-is-not-authorized-for-this-type-of-transaction`	Карта отправителя не разрешена для данного типа транзакции
`card-limits-exceeded`	Превышены ограничения по карте
`card-notauthorized`	Неуспешная авторизация карты
`card-rejected`	Отказ от банка выпустившего карту
`card-reported-stolen`	Карта была объявлена украденной
`card-restrictions`	Ограничения по карте
`check-card-details-or-funds-insufficient`	Проверьте введённые данные, достаточность средств на карте
`client-is-locked`	Услуга В2С не подключена, клиент заблокирован в АРМ ТСП ЗК. Для уточнения статуса обратитесь в SD
`daily-transaction-limit-exceeded`	Превышен дневной лимит транзакций
`description-exceeded`	Превышена разрешенная длина назначения платежа
`error-card-details`	Некорректно введены данные карты
`error-occurred-during-processing`	При обработке произошла ошибка. Воспользуйтесь другой картой
`error-payment-security`	Нарушение безопасности. Обратитесь к эмитенту
`error-retry`	Ошибка. Повторите попытку.
`error-sbp-fio`	У получателя нет расчетного счета в этом банке. ФИО некорректное
`exceeds-amount-limit`	Рекомендовано повторить попытку совершения операции в другой день – после переустановки Эмитентом лимита по общей сумме операций данного типа
`exceeds-frequency-limit`	Превышен предел частоты платежей с данной карты
`expired-card`	Срок действия карты истек
`failed-list-of-bank`	Не удалось получить список банков
`failed-to-complete-the-transaction`	Не удалось провести транзакцию
`failed-to-get-status`	Не удалось получить статус
`failed-to-get-transaction-status`	Не удалось получить статус транзакции
`fraud-suspect`	Подозрение на мошенничество. Обратитесь в Банк
`incorrect-ogrn`	Указан некорректный ОГРН
`inn-max-rollup-amount-exceeded`	Превышен накопительный ежемесячный лимит по расчетному счету
`insufficient-fund`	Недостаточно средств
`insufficient-funds`	Недостаточно средств
`invalid-account`	Недействительный счет
`invalid-card`	Недействительная карта, отказ от эмитента
`invalid-cvv`	Неверный CVV
`invalid-response`	Неверный ответ банка
`invalid-special-condition`	Установлены спец.условия на р/с, ограничивающие проведение операций. Рекомендовано обратиться к сопровождающему менеджеру банка.
`issuer-unavailable`	Эмитент недоступен
`limit-exceeded`	Превышение установленных лимитов
`mismatch-fio`	Несовпадение ФИО получателя
`more-than-one-recipient-found`	Ошибка логики в СБП: Найден больше чем один Получатель
`neresident-rejected`	Запрещены переводы на нерезидентов для данного клиента
`no-access`	Доступ запрещен
`no-connection-to-issuer`	Банк, выпустивший карту, недоступен
`no-or-invalidresponse-received`	Ошибка на стороне эквайера — неверно сформирована транзакция
`no-payment-attempts`	Не было попыток оплаты
`nspk-hourly-limit-exceeded`	Слишком много неудачных попыток за час. Попробуйте снова через час или выберите другой банк получателя
`operation-declined`	Операция отклонена
`operation-failed`	Операция неуспешна. Обратитесь в банк.
`opkc-reject-suspected-fraud`	Отклонено антифродом банка
`opkc-timeout`	Банк получателя не направил ответ НСПК в установленный тайм-аут
`organization-not-found`	Организация не найдена
`payment-not-found`	Платеж не найден
`payout-sbp-rejected`	Банк получателя отклонил выплату.
`re-enter-transaction`	Повторно ввести транзакцию
`recipient-not-found`	Не найден получатель
`recurring-payment-stopped-by-cardholder`	Рекуррентная транзакция была отклонена, поскольку владелец карты остановил эту транзакцию рекуррентного платежа
`refer-to-card-issuer-special-condition`	Обратитесь к эмитенту карты, отказ с по особым условиям
`refusal-from-issuer`	Отказ от эмитента. Обратитесь в Банк
`reject-by-issuer`	Отказ банка-эмитента
`rejected-by-the-anti-fraud`	Отклонено по фроду
`request-timeout`	Операция неуспешна! Не получен ответ от Банка. Повторите операцию позже.
`restricted-card`	Ограничение по карте
`service-not-connected`	Услуга не подключена. Обратитесь в Банк
`suspected-fraud`	Отклонено системой антифрод банка-эмитента
`suspected-malfunction`	Подозрение на неисправность
`system-error`	Системная ошибка
`system-error-sbp`	Системная ошибка в СБП
`system-malfunction`	Неисправность системы
`temp-unavailable`	Перевод временно недоступен, пожалуйста повторите позже
`timeout`	Превышено время выполнения запроса
`token-error`	Связка не найдена
`transaction-ban`	Транзакция запрещена
`transaction-could-not-be-found`	Не удалось найти транзакцию
`transfer-not-allowed`	Перевод не может быть совершен, обратитесь в Банк.
`transfer-not-success`	Перевод не прошел. Повторите операцию
`transfer-restricted`	Ограничение на осуществление перевода. Обратитесь в Банк
`unknown-error`	Произошла непредвиденная ошибка. Обратитесь в поддержку.
`using-another-card`	Транзакция не может быть обработана из-за большого количества повторных попыток оплаты этой картой.
`validation-error`	Ошибка валидации
`violation-of-law`	Платежи для этой карты запрещены
`waiting-time-expired`	Истек срок ожидания ввода данных
`wrong-pin-tries-exceeded`	Неверный пин-код, количество попыток превышено