Conversion (buy)
Reverse conversion: "I want to receive an amount in the target currency, how much do I need to pay in the source currency?". Use this to precisely calculate the payment amount — don't multiply the rate from «Exchange rate»/«Cross rate» by the amount manually.
URL
Request
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
source_ccy |
string | Yes | Numeric code of the payment currency. See «Currency codes». |
target_ccy |
string | Yes | Numeric code of the desired receiving currency. Must differ from source_ccy. |
target_amount |
integer | Yes | Desired amount in the target currency, in minor units. For example, 1000000 = 10,000.00 RUB. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
X-Api-Key |
string | Yes | Shop identifier. |
The X-Signature signature is not required for this method.
Example
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'
Response
{
"source_currency": "840",
"target_currency": "643",
"amount": 11712,
"source_to_base": 12210,
"base_to_target": 143,
"base_currency": "UZS"
}
Response parameters
| Parameter | Type | Description |
|---|---|---|
source_currency |
string | Numeric code of the payment currency. |
target_currency |
string | Numeric code of the desired receiving currency. |
amount |
integer | Amount to pay in minor units of source_currency. Equal to target_amount × base_to_target / source_to_base, rounded. |
source_to_base |
number | Rate of the source currency to the base currency (UZS). |
base_to_target |
number | Rate of the base currency (UZS) to the target currency. |
base_currency |
string | Base settlement currency — always "UZS". |
Calculation formula
amount = round(target_amount × base_to_target / source_to_base)
What this response means
The method does not create a payment operation — it only calculates the amount based on the current rate.
What to do next
Use amount as the final amount to pay in source_currency.
{
"errors": [
{
"code": 20099,
"message": "source_ccy and target_ccy must differ"
}
]
}
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. |
errors[].message |
string | Description of why the request was rejected. |
What this response means
source_ccy and target_ccy are the same — converting a currency into itself makes no sense.
What to do next
Pass two different currency codes and retry the request.
{
"errors": [
{
"code": 20044,
"message": "The integration with Montra is not configured for the shop"
}
]
}
Response parameters
| Parameter | Type | Description |
|---|---|---|
errors |
array | List of errors. Codes and handling recommendations are given in «HTTP response errors». |
errors[].code |
integer | 20044 — integration is not connected; 20099 — the rate for one of the currencies is unavailable from the provider. |
errors[].message |
string | Description of the cause. |
What this response means
For code 20044, contact KVELL support to connect the rates provider integration.
For code 20099, check the currency codes in source_ccy/target_ccy.
What to do next
Fix the cause of the error and retry the request.
{
"errors": [
{
"code": 20098,
"message": "target_amount: Field required"
}
]
}
Response parameters
| Parameter | Type | Description |
|---|---|---|
errors |
array | List of validation errors. |
errors[].code |
integer | Error code. |
errors[].message |
string | The field and reason for the validation error. |
What this response means
A required parameter was not passed, or it doesn't match the expected format.
What to do next
Fix the field from errors[].message and retry the request.
{
"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. |
errors[].message |
string | Description of the technical error. |
What this response means
The method does not create a financial operation — a technical error cannot lead to an undefined result.
What to do next
It's safe to retry the same request. If the error persists, contact KVELL support and provide
the URL, request time, HTTP code, code, and message.