Retrieving transaction status

Returns the current status and detailed information about a payment or payout by the transaction identifier in the merchant's system. The method does not change the state of the operation.

Integration flow

Save the transaction passed when the operation was created.
Generate a signature from X-Api-Key, transaction, and secret_key.
Send the status request with the same X-Api-Key used to create the operation.
If you receive new or processing, obtain the final status one of two ways: poll the method every 2 minutes, or use the callback that KVELL sends after the operation completes.
For canceled, use error_code and error_message to determine the reason for the decline.

When to request the status

Use this method after creating the operation, while it is being processed. Requesting the status is also mandatory if a 5XX, a timeout, or a connection drop occurred when creating the operation.

If a 5XX, timeout, or connection drop occurs while requesting the status, retry the same request with the original transaction. These errors do not determine the outcome of the operation — wait for a 200 response and check the status field.

URL

ProductionStage

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

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

Request

Path parameters

Parameter	Type	Required	Description
`transaction`	string	Yes	Operation identifier in the merchant's system.

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop identifier.
`X-Signature`	string	Yes	Request signature.

Building the signature

Concatenate X-Api-Key, transaction, and secret_key without separators, compute the SHA-256 hash of the resulting UTF-8 encoded string, and pass the hash in lowercase in the X-Signature header.

SHA256(X-Api-Key + transaction + 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.pay.kvell.group/v1/orders/payment-20260807-0001' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>'

Response

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

HTTP 200 is the result of the status request, not necessarily a successful operation

The operation was found, but its business outcome is determined by the status field. The values new and processing are not final.

If no HTTP response is received

A timeout or connection drop does not change the transaction status and does not mean it completed successfully or unsuccessfully. Safely retry the same GET request with the original transaction.

2004004034044225XX

Example 200 (OK) response

{
  "id": "b13e1610-f26a-4c49-84e8-0edf1650a026",
  "status": "completed",
  "transaction": "payment-20260807-0001",
  "amount": 15000,
  "commission": 150,
  "inner_commission": 50,
  "description": "Payment for order 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"
}

Response parameters

Parameter	Type	Description
`id`	string	Operation identifier in KVELL.
`status`	string	Current status. Possible values are listed in «Transaction statuses».
`transaction`	string	Operation identifier in the merchant's system.
`amount`	integer	Operation amount in kopecks.
`commission`	integer	External fee in kopecks.
`inner_commission`	integer	Internal fee in kopecks.
`description`	string \| null	Operation description.
`success_url`	string \| null	URL to redirect to after a successful operation.
`fail_url`	string \| null	URL to redirect to after a failed operation.
`redirect_url`	string	Final URL to redirect the user to. If no URL is set on the operation, the KVELL payment page address is returned.
`extra_data`	object	Additional data passed by the merchant.
`fiscal_data`	object \| null	Fiscalization data.
`additional_data`	object	Additional data generated while processing the operation. If there is no data, an empty object `{}` is returned.
`error_code`	string \| null	The reason code for the decline. Possible values are listed in «Transaction error codes». `null` is returned for an operation that was not declined.
`error_message`	string \| null	Description of the decline reason. `null` is returned for an operation that was not declined.
`created_at`	string	Date and time the operation was created, in ISO 8601 format.
`refund_amount`	integer \| null	Amount of refunds performed, in kopecks.
`reverse_amount`	integer \| null	Amount of authorization reversals performed, in kopecks.
`confirm_amount`	integer \| null	Amount of confirmations performed, in kopecks.
`instrument`	string \| null	Payment or payout method. The main values are listed in «Instruments».
`ecommerce_type`	string \| null	Operation type. Possible values are listed in «Transaction types».

What this response means

The transaction was found. HTTP code 200 confirms the data was retrieved successfully, but the outcome of the operation must be determined from the status field.

Example 400 (Bad Request) response

{
  "errors": [
    {
      "code": 20002,
      "message": "Invalid signature"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20002` for an invalid signature.
`errors[].message`	string	Description of why the request was rejected.

Example 403 (Forbidden) response

{
  "errors": [
    {
      "code": 20037,
      "message": "Access denied"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20037` for access denial.
`errors[].message`	string	Description of the reason for access denial.

Example 404 (Not Found) response

{
  "errors": [
    {
      "code": 20009,
      "message": "Order not found"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20009` for a transaction not found; `20006` for a shop not found.
`errors[].message`	string	Description of why the resource was not found.

What this response means

Code 20009 means that no transaction with the given transaction was found for the shop identified by the X-Api-Key header. This is a lookup error, not a final transaction status: the response does not contain the status, error_code, or error_message fields.

Possible causes:

an incorrect transaction was passed in the URL;
the request was sent with the X-Api-Key of a different shop — transactions of different shops are isolated;
the wrong environment was selected: Production instead of Stage, or vice versa;
the original request failed before the transaction was created, for example due to validation or an invalid signature;
the status was requested before the original creation request had finished.

What to do next

Check the transaction, X-Api-Key, and the selected environment.
Do not retry the status request with the same data: until the cause is resolved, the method will return 404 again.
If the original creation request is still in progress, wait for it to finish first.
If the operation was created successfully and the identifiers are correct, contact support and provide the transaction.

Example 422 (Unprocessable Entity) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Validation error code — `20098`.
`errors[].message`	string	Field name and reason for the validation error.

Example 5XX (Internal Server Error) response

{
  "errors": [
    {
      "code": 20000,
      "message": "Unknown error"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20000` for an unknown error.
`errors[].message`	string	Description of the technical error.

5XX, timeout, and connection drop

In these cases the current state of the transaction is unknown to the client. A technical error in the status request is not the result of the original payment or payout and does not change it.

Common handling algorithm

Leave the original operation in its current state in your system.
Safely retry the same GET request with the original transaction.
Continue processing only after receiving 200 and checking the status field.
If the technical error persists, contact support and provide the transaction.

Do not create a new operation based on a technical error

An error from the status method says nothing about the outcome of the original transaction.

Transaction statuses

Status	Final	What it means and what to do
`new`	No	The transaction was created, but processing has not started yet.
`processing`	No	The transaction is being processed.
`completed`	Yes	The operation completed successfully.
`canceled`	Yes	The operation was declined. Use `error_code` and `error_message` to determine the reason.
`refunded`	Yes	A full refund of the payment was made.
`part_refunded`	Yes	A partial refund was made. The current refund amount is given in `refund_amount`.
`reversed`	Yes	The authorization was fully reversed.
`part_reversed`	Yes	The authorization was partially reversed. The current reversal amount is given in `reverse_amount`.
`confirmed`	Yes	The authorization was fully confirmed.
`part_confirmed`	Yes	The authorization was partially confirmed. The current confirmation amount is given in `confirm_amount`.

Transaction types

Value	Description
`payment`	Payment.
`payout`	Payout.
`unknown`	The operation type is not determined.
`null`	No type, for example for a previously created transaction.

Instruments

The set of values depends on which payment and payout methods are connected. Main values:

Value	Description
`card`	Bank card.
`sbp`	Faster Payments System (SBP).
`tpay`	T-Pay.
`alfapay`	Alfa-Pay.
`sberpay`	Sber-Pay.
`sbpb2b`	SBP B2B.
`smartcontract`	Payout via smart contract.
`sbpstaticqr`	Static SBP QR code.
`null`	No method specified, for example for a previously created transaction.

Additional data

For an SBP payment via Alfa-Bank followed by binding, additional_data may contain:

Parameter	Type	Description
`bank_id`	string	Identifier of the payer's bank.
`subscription_token`	string	Identifier of the payer's account binding at the bank.

Transaction error codes

The error_code field contains the reason the operation was declined when the status is canceled. These are business codes from payment systems and banks, not API HTTP request errors. The API's own errors are listed separately in «HTTP response errors».

Code	Description
`3ds-error`	3-D Secure authorization error
`access-denied`	Access denied
`account-restrictions`	Card account restriction
`amount-exceeded`	The operation amount limit has been exceeded. Contact the bank
`amount-exceeds-card-ceiling`	This amount exceeds the allowed limit and cannot be processed on this card
`amount-exceeds-maximum-allowed-value`	The amount exceeds the maximum allowed value
`amount-limit`	The transaction was declined because the payment amount exceeded the set limits.
`an-error-occurred-during-3ds-processing`	Error during 3DS processing
`authentication-failed`	Contact your bank or use a different card
`authorization-declined`	Authorization declined. Check the card details entered or use a different card
`available-card-limit-exceeded`	The available card limit has been exceeded
`banned-operation`	Declined by the anti-fraud system. The operation is blocked. Use a different card
`card-blocking`	The transaction was declined because the card is on a blacklist
`card-expired`	The card has expired
`card-is-blocked`	The maximum number of PIN entry attempts was exceeded. The card may be temporarily blocked
`card-is-lost`	The card has been reported lost
`card-is-not-authorized-for-this-type-of-transaction`	The sender's card is not authorized for this type of transaction
`card-limits-exceeded`	Card limits exceeded
`card-notauthorized`	Card authorization failed
`card-rejected`	Declined by the card-issuing bank
`card-reported-stolen`	The card has been reported stolen
`card-restrictions`	Card restrictions
`check-card-details-or-funds-insufficient`	Check the details entered and whether the card has sufficient funds
`client-is-locked`	The B2C service is not connected, the client is locked in the merchant's workstation. Contact SD (Service Desk) to clarify the status
`daily-transaction-limit-exceeded`	The daily transaction limit has been exceeded
`description-exceeded`	The allowed length of the payment purpose has been exceeded
`error-card-details`	The card details entered are incorrect
`error-occurred-during-processing`	An error occurred during processing. Use a different card
`error-payment-security`	Security violation. Contact the issuer
`error-retry`	Error. Please try again.
`error-sbp-fio`	The recipient has no settlement account at this bank. The full name is incorrect
`exceeds-amount-limit`	It is recommended to retry the operation on another day — after the issuer resets the limit on the total amount of this type of operation
`exceeds-frequency-limit`	The payment frequency limit for this card has been exceeded
`expired-card`	The card has expired
`failed-list-of-bank`	Failed to retrieve the list of banks
`failed-to-complete-the-transaction`	Failed to complete the transaction
`failed-to-get-status`	Failed to retrieve the status
`failed-to-get-transaction-status`	Failed to retrieve the transaction status
`fraud-suspect`	Suspected fraud. Contact the bank
`incorrect-ogrn`	An invalid OGRN was specified
`inn-max-rollup-amount-exceeded`	The cumulative monthly limit on the settlement account has been exceeded
`insufficient-fund`	Insufficient funds
`insufficient-funds`	Insufficient funds
`invalid-account`	Invalid account
`invalid-card`	Invalid card, declined by the issuer
`invalid-cvv`	Invalid CVV
`invalid-payee-requisites`	Error in the payee's bank details
`invalid-response`	Invalid response from the bank
`invalid-special-condition`	Special conditions are set on the settlement account that restrict operations. It is recommended to contact your bank relationship manager
`issuer-unavailable`	The issuer is unavailable
`limit-exceeded`	Set limits exceeded
`mismatch-fio`	The recipient's full name does not match
`more-than-one-recipient-found`	Logic error in SBP: more than one recipient found
`neresident-rejected`	Transfers to non-residents are prohibited for this client
`no-access`	Access denied
`no-connection-to-issuer`	The card-issuing bank is unavailable
`no-or-invalidresponse-received`	Error on the acquirer's side — the transaction was formed incorrectly
`no-payment-attempts`	No payment attempts were made
`nspk-hourly-limit-exceeded`	Too many failed attempts within an hour. Try again in an hour or choose a different recipient bank
`operation-declined`	The operation was declined
`operation-failed`	The operation failed. Contact the bank.
`opkc-reject-suspected-fraud`	Declined by the bank's anti-fraud system
`opkc-timeout`	The recipient's bank did not send a response to NSPK within the set timeout
`organization-not-found`	Organization not found
`payment-not-found`	Payment not found
`payment-order-deleted`	The payment order was deleted at the bank
`payout-requisites-rejected`	The bank rejected the payment order
`payout-sbp-rejected`	The recipient's bank rejected the payout.
`re-enter-transaction`	Re-enter the transaction
`recipient-not-found`	Recipient not found
`recurring-payment-stopped-by-cardholder`	The recurring transaction was declined because the cardholder stopped this recurring payment transaction
`refer-to-card-issuer-special-condition`	Contact the card issuer, declined due to special conditions
`refusal-from-issuer`	Declined by the issuer. Contact the bank
`reject-by-issuer`	Declined by the issuing bank
`rejected-by-the-anti-fraud`	Declined by anti-fraud
`request-timeout`	The operation failed! No response was received from the bank. Please retry later.
`restricted-card`	Card restriction
`service-not-connected`	The service is not connected. Contact the bank
`suspected-fraud`	Declined by the issuing bank's anti-fraud system
`suspected-malfunction`	Suspected malfunction
`system-error`	System error
`system-error-sbp`	System error in SBP
`system-malfunction`	System malfunction
`temp-unavailable`	The transfer is temporarily unavailable, please try again later
`timeout`	The request execution time was exceeded
`token-error`	Binding not found
`transaction-ban`	The transaction is prohibited
`transaction-could-not-be-found`	Failed to find the transaction
`transfer-not-allowed`	The transfer cannot be made, contact the bank.
`transfer-not-success`	The transfer failed. Retry the operation
`transfer-restricted`	Restriction on making the transfer. Contact the bank
`unknown-error`	An unexpected error occurred. Contact support.
`using-another-card`	The transaction cannot be processed due to a large number of repeated payment attempts with this card.
`validation-error`	Validation error
`violation-of-law`	Payments are prohibited for this card
`waiting-time-expired`	The waiting time for data entry has expired
`wrong-pin-tries-exceeded`	Incorrect PIN, number of attempts exceeded