Список транзакций

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

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

Сформируйте уникальный X-Request-ID в формате UUID v4.
Сформируйте подпись из X-Api-Key, X-Request-ID и secret_key.
Передайте параметры пагинации и при необходимости добавьте фильтры status, date_from и date_to.
Используйте поля page, pages и total из ответа для перехода по страницам.
Если нужен актуальный результат отдельной операции, запросите статус транзакции по значению transaction.

URL

ProductionStage

GET https://api.baas.kvell.group/v1/orders

GET https://api.baas.stage.kvell.group/v1/orders

Запрос

Query-параметры

Параметр	Тип	Обязательно	Описание
`page`	integer	Нет	Номер страницы, начиная с `1`. По умолчанию — `1`.
`size`	integer	Нет	Количество транзакций на странице: от `1` до `100`. По умолчанию — `50`.
`status`	string	Нет	Статус транзакции. Возможные значения приведены в разделе «Статусы транзакции».
`date_from`	string	Нет	Начало периода создания транзакций в формате ISO 8601. Передается время в UTC, например `2026-08-01T00:00:00Z`.
`date_to`	string	Нет	Конец периода создания транзакций в формате ISO 8601. Передается время в UTC, например `2026-08-10T23:59:59Z`.

Заголовки

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

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

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

SHA256(X-Api-Key + X-Request-ID + secret_key)

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

Пример

cURL

curl --request GET \
  --url 'https://api.baas.kvell.group/v1/orders?page=1&size=50&status=completed&date_from=2026-08-01T00%3A00%3A00Z&date_to=2026-08-10T23%3A59%3A59Z' \
  --header 'X-Api-Key: 11111111-1111-4111-8111-111111111111' \
  --header 'X-Request-ID: e72ebb15-58d4-496d-891d-00c806f0fdf2' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'

Ответ

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

2004014034044225XX

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

{
  "items": [
    {
      "id": "3b3c19f4-c680-4f5d-bf2e-c0835439cf12",
      "description": "Выплата по договору 42",
      "transaction": "payout-20260806-0001",
      "amount": 15000,
      "commission": 150,
      "inner_commission": 50,
      "status": "completed",
      "created_at": "2026-08-06T09:15:27.231000+00:00",
      "instrument": "card",
      "extra_data": {},
      "payment": {},
      "payout": {
        "card_mask": "411111**1111"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50,
  "pages": 1
}

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

Параметр	Тип	Описание
`items`	array	Транзакции на текущей странице. Если подходящих транзакций нет, возвращается пустой массив `[]`.
∟ `id`	string	Идентификатор операции в KVELL.
∟ `description`	string \| null	Описание платежа или назначение выплаты.
∟ `transaction`	string	Идентификатор операции в системе мерчанта.
∟ `amount`	integer	Сумма операции в копейках.
∟ `commission`	integer	Внешняя комиссия в копейках.
∟ `inner_commission`	integer	Внутренняя комиссия в копейках.
∟ `status`	string	Текущий статус. Возможные значения приведены в разделе «Статусы транзакции».
∟ `created_at`	string	Дата и время создания операции в формате ISO 8601.
∟ `instrument`	string \| null	Способ оплаты или выплаты. Основные значения приведены в разделе «Способы проведения операции».
∟ `extra_data`	object	Дополнительные данные мерчанта. Если данных нет, возвращается пустой объект `{}`.
∟ `payment`	object	Данные транзакции платежа. Для выплаты возвращается пустой объект `{}`.
∟ `card_mask`	string \| null	Маска карты платежа. Поле возвращается, если для операции найдены данные платежа; для некарточного способа значение может быть `null`.
∟ `payout`	object	Данные транзакции выплаты. Для платежа возвращается пустой объект `{}`.
∟ `card_mask`	string \| null	Маска карты выплаты. Поле возвращается, если для операции найдены данные выплаты; для некарточного способа значение может быть `null`.
`total`	integer	Общее количество транзакций, соответствующих фильтрам.
`page`	integer	Номер текущей страницы.
`size`	integer	Запрошенное количество транзакций на странице.
`pages`	integer	Общее количество страниц. Если транзакций нет, возвращается `0`.

Пример ответа 401 (Unauthorized)

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

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

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

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

Проверьте X-Api-Key, X-Request-ID, secret_key и порядок конкатенации.
Пересчитайте подпись и повторите запрос.

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

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

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

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

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

Убедитесь, что магазин активен и ему разрешён доступ к BAAS API. При необходимости обратитесь к менеджеру KVELL.

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

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

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

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

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

Магазин с переданным X-Api-Key не найден в выбранном контуре. Это не означает, что у магазина нет транзакций: при пустом списке метод возвращает 200, items: [] и total: 0.

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

{
  "errors": [
    {
      "code": 0,
      "message": "Input should be less than or equal to 100",
      "field": "size"
    }
  ]
}

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

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

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

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

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

Параметр	Тип	Описание
`errors`	array	Список технических ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки BAAS API».
`errors[].code`	integer	Код ошибки. Для неизвестной ошибки — `1`; для ошибки зависимого сервиса может вернуться `4`.
`errors[].message`	string	Описание технической ошибки.

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

Техническая ошибка не изменяет состояние транзакций и не определяет их бизнес-результат.

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

Безопасно повторите тот же GET-запрос с исходными query-параметрами.
Сформируйте новый X-Request-ID и пересчитайте X-Signature.
Продолжайте обработку только после получения 200.
Если техническая ошибка повторяется, обратитесь в поддержку и передайте X-Request-ID запросов.