Creating a payment session

This method saves the amount and parameters of a future payment. Creating a session is a mandatory first step before paying by card via H2H, SBP, or Alfa-Pay.

A successful response only means the session data was saved. The payment and transaction in KVELL are not created at this stage yet.

Integration flow

Generate a unique transaction for the future payment and prepare the amount, description, and additional parameters.
Sign transaction and amount, then send the request to create the session.
After receiving a 200 response, within 20 minutes call the method of the chosen payment method, passing the same transaction: card payment via H2H, SBP, or Alfa-Pay.
After the payment is created, determine its result via the status retrieval method or callback.

The session is valid for 20 minutes

If the payment method is not called within this time, the session data is deleted. The next payment request will return error 20004 — "Session not found". In this case, create a new session with the same transaction, then call the chosen payment method again.

URL

ProductionStage

POST https://api.pay.kvell.group/v1/orders/session

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

Request

Headers

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

Generating the signature

Combine X-Api-Key, transaction, amount, and secret_key with no separators. Calculate SHA-256 of the resulting UTF-8 encoded string and pass the lowercase hex hash in the X-Signature header.

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

secret_key is found in the shop settings. Spaces, line breaks, and other separators must not be added.

Request body

Parameter	Type	Required	Description
`transaction`	string	Yes	Unique transaction identifier in the merchant's system.
`amount`	integer	Yes	Payment amount in kopecks. For example, `15000` is 150 ₽.
`description`	string	Yes	Transaction description, no more than 500 characters. Do not pass personal or payment data in this field.
`success_url`	string	No	Merchant URL for a successful payment result, no more than 2083 characters.
`fail_url`	string	No	Merchant URL for an unsuccessful payment result, no more than 2083 characters.
`redirect_url`	string	Conditional	URL to return the user to after the browser flow, no more than 2083 characters. Required for direct H2H integration if the user needs to be returned to the merchant's site.
`extra_data`	object	No	Arbitrary additional merchant data. Returned in the transaction information and callback.
`fiscal_data`	object	No	Data for receipt fiscalization under 54-FZ.
`split_data`	array	No	Data for payment splitting.

Return URL for H2H

For card payments via H2H, pass redirect_url. After 3-D Secure completes, KVELL will redirect the user to this address regardless of the payment's business outcome. Determine success or failure from the transaction status, not from the fact of the redirect.

Example

JSONcURL

{
  "transaction": "payment-20260810-0001",
  "amount": 15000,
  "description": "Payment for order 42",
  "success_url": "https://merchant.example/payment/success",
  "fail_url": "https://merchant.example/payment/fail",
  "redirect_url": "https://merchant.example/payment/result",
  "extra_data": {
    "order_id": "42"
  }
}

curl --request POST \
  --url 'https://api.pay.kvell.group/v1/orders/session' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>' \
  --data '{
    "transaction": "payment-20260810-0001",
    "amount": 15000,
    "description": "Payment for order 42",
    "success_url": "https://merchant.example/payment/success",
    "fail_url": "https://merchant.example/payment/fail",
    "redirect_url": "https://merchant.example/payment/result",
    "extra_data": {
      "order_id": "42"
    }
  }'

Response

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

2004004034044225XX

Example 200 (OK) response

{
  "ok": true
}

Response parameters

Parameter	Type	Description
`ok`	boolean	`true` — the session data was saved.

What this response means

The session was created, but the payment and transaction have not been created yet. The response is not the result of the payment.

What to do next

Within 20 minutes, call the method of the chosen payment method with the same transaction.

Example 400 (Bad Request) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. See «HTTP response errors» for codes and handling recommendations.
`errors[].code`	integer	Error code. In the example — `20002`.
`errors[].message`	string	Description of why the request was rejected.

What this response means

The request was rejected, and the session was not created. Possible reasons include an invalid signature and the shop not having a payment profile.

What to do next

Fix the cause of the error and repeat the request with the same transaction. For 20003, contact your KVELL account manager to set up a payment profile.

Example 403 (Forbidden) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. See «HTTP response errors» for codes and handling recommendations.
`errors[].code`	integer	Error code. For access denial — `20037`.
`errors[].message`	string	Description of the reason access was denied.

What this response means

The shop is inactive or has been denied access to the API. The session was not created.

What to do next

Check the shop's status and repeat the request only after access is restored.

Example 404 (Not Found) response

{
  "errors": [
    {
      "code": 20006,
      "message": "Shop not found"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. See «HTTP response errors» for codes and handling recommendations.
`errors[].code`	integer	Error code. In the example — `20006`.
`errors[].message`	string	Description of why the shop was not found.

What this response means

The shop for the passed X-Api-Key was not found in the selected environment. The session was not created.

What to do next

Check X-Api-Key and the Stage/Production environment.

Example 422 (Unprocessable Entity) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. See «HTTP response errors» for codes and handling recommendations.
`errors[].code`	integer	Validation error code. For a field error — `20098`.
`errors[].message`	string	Field name and reason for the validation error.

What this response means

The request headers or body failed validation for required fields or format. The session was not created.

What to do next

Fix the fields from errors[].message, regenerate the signature, and repeat the request with the same transaction.

Example 5XX (Internal Server Error) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. See «HTTP response errors» for codes and handling recommendations.
`errors[].code`	integer	Error code. For an unknown error — `20000`.
`errors[].message`	string	Description of the technical error.

What this response means

The payment and transaction are not created by this method. The only thing unknown to the client is whether the temporary session was saved.

What to do next

Repeat the same request with the same transaction and an unchanged body.
After receiving a 200 response, proceed to the payment method.
If the technical error persists, contact support and provide the transaction.