Перейти к содержанию

Конвертация (buy)

Reverse-конвертация: «хочу получить сумму в целевой валюте, сколько нужно заплатить в исходной валюте?». Используйте для точного расчёта суммы платежа — не умножайте курс из «Курс валюты»/«Кросс-курс» на сумму вручную.

URL

GET https://api.pay.kvell.group/v1/currency/convert/buy

GET https://api.pay.stage.kvell.group/v1/currency/convert/buy

Запрос

Query-параметры

Параметр Тип Обязательно Описание
source_ccy string Да Числовой код валюты оплаты. См. «Коды валют».
target_ccy string Да Числовой код желаемой валюты получения. Должен отличаться от source_ccy.
target_amount integer Да Желаемая сумма в целевой валюте, в минорных единицах. Например, 1000000 = 10 000.00 RUB.

Заголовки

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

Подпись X-Signature для этого метода не требуется.

Пример

curl --request GET \
  --url 'https://api.pay.stage.kvell.group/v1/currency/convert/buy?source_ccy=840&target_ccy=643&target_amount=1000000' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000'

Ответ

Пример ответа 200 (OK)
{
  "source_currency": "840",
  "target_currency": "643",
  "amount": 11712,
  "source_to_base": 12210,
  "base_to_target": 143,
  "base_currency": "UZS"
}

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

Параметр Тип Описание
source_currency string Числовой код валюты оплаты.
target_currency string Числовой код желаемой валюты получения.
amount integer Сумма к оплате в минорных единицах source_currency. Равно округлённому target_amount × base_to_target / source_to_base.
source_to_base number Курс исходной валюты к базовой (UZS).
base_to_target number Курс базовой валюты (UZS) к целевой.
base_currency string Базовая валюта расчёта — всегда "UZS".

Формула расчёта

amount = round(target_amount × base_to_target / source_to_base)

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

Метод не создаёт операцию платежа — только рассчитывает сумму на основе текущего курса.

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

Используйте amount как итоговую сумму к оплате в source_currency.

Пример ответа 400 (Bad Request)
{
  "errors": [
    {
      "code": 20099,
      "message": "source_ccy and target_ccy must differ"
    }
  ]
}

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

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

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

source_ccy и target_ccy совпадают — конвертация валюты в саму себя не имеет смысла.

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

Передайте два разных кода валют и повторите запрос.

Пример ответа 404 (Not Found)
{
  "errors": [
    {
      "code": 20044,
      "message": "Интеграция с Montra не настроена для магазина"
    }
  ]
}

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

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

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

Для кода 20044 обратитесь в поддержку KVELL, чтобы подключить интеграцию с провайдером курсов. Для кода 20099 проверьте коды валют в source_ccy/target_ccy.

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

Устраните причину ошибки и повторите запрос.

Пример ответа 422 (Unprocessable Entity)
{
  "errors": [
    {
      "code": 20098,
      "message": "target_amount: Field required"
    }
  ]
}

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

Параметр Тип Описание
errors array Список ошибок валидации.
errors[].code integer Код ошибки.
errors[].message string Поле и причина ошибки валидации.

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

Не передан обязательный параметр или он не соответствует формату.

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

Исправьте поле из errors[].message и повторите запрос.

Пример ответа 5XX (Internal Server Error)
{
  "errors": [
    {
      "code": 20000,
      "message": "Неизвестная ошибка"
    }
  ]
}

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

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

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

Метод не создаёт финансовую операцию — техническая ошибка не может привести к неопределённому результату.

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

Безопасно повторите тот же запрос. Если ошибка повторяется, обратитесь в поддержку KVELL и передайте URL, время запроса, HTTP-код, code и message.