List of transactions

Returns a list of the shop's payment and payout transactions, with the option to filter by status and creation period.

Integration flow

Generate a unique X-Request-ID in UUID v4 format.
Generate a signature from X-Api-Key, X-Request-ID, and secret_key.
Pass the pagination parameters and, if needed, add the status, date_from, and date_to filters.
Use the page, pages, and total fields from the response to page through results.
If you need the current result of a specific operation, request the transaction status by transaction value.

URL

ProductionStage

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

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

Request

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number, starting from `1`. Default — `1`.
`size`	integer	No	Number of transactions per page: from `1` to `100`. Default — `50`.
`status`	string	No	Transaction status. Possible values are listed in «Transaction statuses».
`date_from`	string	No	Start of the transaction creation period in ISO 8601 format. Time is passed in UTC, e.g. `2026-08-01T00:00:00Z`.
`date_to`	string	No	End of the transaction creation period in ISO 8601 format. Time is passed in UTC, e.g. `2026-08-10T23:59:59Z`.

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop identifier in UUID format.
`X-Request-ID`	string	Yes	Unique request identifier in UUID v4 format. Used when generating the signature.
`X-Signature`	string	Yes	Request signature.

Generating the signature

Concatenate X-Api-Key, X-Request-ID, and secret_key with no separators, compute SHA-256 of the resulting string in UTF-8 encoding, and pass the lowercase hash in the X-Signature header.

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

secret_key is found in the shop's settings. The order of the values must not be changed.

Example

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'

Response

Select an HTTP code to see the example, response parameters, and recommended actions.

2004014034044225XX

Example 200 (OK) response

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

Response parameters

Parameter	Type	Description
`items`	array	Transactions on the current page. If there are no matching transactions, an empty array `[]` is returned.
∟ `id`	string	Operation identifier in KVELL.
∟ `description`	string \| null	Payment description or payout purpose.
∟ `transaction`	string	Operation identifier in the merchant's system.
∟ `amount`	integer	Operation amount in kopecks.
∟ `commission`	integer	External commission in kopecks.
∟ `inner_commission`	integer	Internal commission in kopecks.
∟ `status`	string	Current status. Possible values are listed in «Transaction statuses».
∟ `created_at`	string	Operation creation date and time in ISO 8601 format.
∟ `instrument`	string \| null	Payment or payout method. Main values are listed in «Operation methods».
∟ `extra_data`	object	Additional merchant data. An empty object `{}` is returned if there is no data.
∟ `payment`	object	Payment transaction data. An empty object `{}` is returned for a payout.
∟ `card_mask`	string \| null	Payment card mask. This field is returned if payment data was found for the operation; for a non-card method, the value may be `null`.
∟ `payout`	object	Payout transaction data. An empty object `{}` is returned for a payment.
∟ `card_mask`	string \| null	Payout card mask. This field is returned if payout data was found for the operation; for a non-card method, the value may be `null`.
`total`	integer	Total number of transactions matching the filters.
`page`	integer	Current page number.
`size`	integer	Requested number of transactions per page.
`pages`	integer	Total number of pages. If there are no transactions, `0` is returned.

Example 401 (Unauthorized) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «BAAS API errors».
`errors[].code`	integer	Error code. For an invalid signature — `11`.
`errors[].message`	string	Description of why the request was rejected.

What to do next

Check X-Api-Key, X-Request-ID, secret_key, and the concatenation order.
Recompute the signature and retry the request.

Example 403 (Forbidden) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «BAAS API errors».
`errors[].code`	integer	Error code. For an inactive shop — `12`.
`errors[].message`	string	Description of why access was denied.

What to do next

Make sure the shop is active and has access to the BAAS API. If needed, contact your KVELL manager.

Example 404 (Not Found) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «BAAS API errors».
`errors[].code`	integer	Error code. For a shop that was not found — `20`.
`errors[].message`	string	Description of why the data was not found.

What this response means

No shop was found for the given X-Api-Key on the selected environment. This does not mean the shop has no transactions: for an empty list, the method returns 200, items: [], and total: 0.

Example 422 (Unprocessable Entity) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and handling recommendations are given in «BAAS API errors».
`errors[].code`	integer	Field validation error code — `0`.
`errors[].message`	string	Reason for the validation error.
`errors[].field`	string	Header or query parameter with an invalid value.

Example 5XX (Internal Server Error) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of technical errors. Codes and handling recommendations are given in «BAAS API errors».
`errors[].code`	integer	Error code. For an unknown error — `1`; for a dependent service error, `4` may be returned.
`errors[].message`	string	Description of the technical error.

5XX, timeout, and connection loss

A technical error does not change the state of transactions and does not determine their business result.

Unified handling algorithm

Safely retry the same GET request with the original query parameters.
Generate a new X-Request-ID and recompute X-Signature.
Continue processing only after receiving 200.
If the technical error persists, contact support and provide the X-Request-ID values of the requests.