Создание платёжной сессии

Метод сохраняет сумму и параметры будущего платежа. Создание сессии является обязательным первым шагом перед оплатой картой через H2H, СБП или Alfa-Pay.

Успешный ответ означает только то, что данные сессии сохранены. Платёж и транзакция в KVELL на этом этапе ещё не создаются.

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

Сформируйте уникальный transaction для будущего платежа и подготовьте сумму, описание и дополнительные параметры.
Подпишите transaction и amount, затем отправьте запрос на создание сессии.
После ответа 200 в течение 20 минут вызовите метод выбранного способа оплаты, передав тот же transaction: оплата картой через H2H, СБП или Alfa-Pay.
После создания платежа определяйте его результат через метод получения статуса или колбэк.

Сессия действует 20 минут

Если за это время не вызвать метод проведения платежа, данные сессии удаляются. Следующий запрос платежа вернёт ошибку 20004 — «Сессия не найдена». В этом случае повторно создайте сессию с тем же transaction, а затем снова вызовите выбранный способ оплаты.

URL

ProductionStage

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

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

Запрос

Заголовки

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

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

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

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

secret_key находится в настройках магазина. Пробелы, переносы строк и другие разделители добавлять нельзя.

Тело запроса

Параметр	Тип	Обязательно	Описание
`transaction`	string	Да	Уникальный идентификатор транзакции в системе мерчанта.
`amount`	integer	Да	Сумма платежа в копейках. Например, `15000` — 150 ₽.
`description`	string	Да	Описание к транзакции, не более 500 символов. Не передавайте в поле персональные или платёжные данные.
`success_url`	string	Нет	URL мерчанта для успешного результата платежа, не более 2083 символов.
`fail_url`	string	Нет	URL мерчанта для неуспешного результата платежа, не более 2083 символов.
`redirect_url`	string	Условно	URL возврата пользователя после браузерного сценария, не более 2083 символов. Обязателен для прямой H2H-интеграции, если пользователя необходимо вернуть на сайт мерчанта.
`extra_data`	object	Нет	Произвольные дополнительные данные мерчанта. Возвращаются в информации о транзакции и колбэке.
`fiscal_data`	object	Нет	Данные для фискализации чека по 54-ФЗ.
`split_data`	array	Нет	Данные для сплитования платежа.

URL возврата для H2H

Для оплаты картой через H2H передавайте redirect_url. После завершения 3-D Secure KVELL перенаправит пользователя на этот адрес независимо от бизнес-результата платежа. Успех или отказ определяйте по статусу транзакции, а не по факту редиректа.

Пример

JSONcURL

{
  "transaction": "payment-20260810-0001",
  "amount": 15000,
  "description": "Оплата заказа 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": "Оплата заказа 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"
    }
  }'

Ответ

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

2004004034044225XX

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

{
  "ok": true
}

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

Параметр	Тип	Описание
`ok`	boolean	`true` — данные сессии сохранены.

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

Сессия создана, но платёж и транзакция ещё не созданы. Ответ не является результатом оплаты.

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

В течение 20 минут вызовите метод выбранного способа оплаты с тем же transaction.

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

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

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

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

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

Запрос отклонён, сессия не создана. Возможные причины включают неверную подпись и отсутствие платёжного профиля у магазина.

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

Исправьте причину ошибки и повторите запрос с тем же transaction. Для 20003 обратитесь к менеджеру KVELL, чтобы подключить платёжный профиль.

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

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

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

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

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

Магазин не активен или ему запрещён доступ к API. Сессия не создана.

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

Проверьте статус магазина и повторите запрос только после восстановления доступа.

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

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

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

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

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

Магазин для переданного X-Api-Key не найден в выбранном контуре. Сессия не создана.

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

Проверьте X-Api-Key и контур Stage/Production.

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

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

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

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

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

Заголовки или тело запроса не прошли проверку обязательных полей и формата. Сессия не создана.

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

Исправьте поля из errors[].message, заново сформируйте подпись и повторите запрос с тем же transaction.

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

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

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

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

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

Платёж и транзакция не создаются этим методом. Клиенту неизвестно только то, сохранилась ли временная сессия.

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

Повторите тот же запрос с тем же transaction и неизменным телом.
После ответа 200 перейдите к методу проведения платежа.
Если техническая ошибка повторяется, обратитесь в поддержку и передайте transaction.