Conversion (sell)
Forward conversion: "I have an amount in the source currency, how much will I receive in the target currency?". Use this to precisely calculate the amount to be received when transferring funds — 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 source currency. See «Currency codes». |
target_ccy |
string | Yes | Numeric code of the target currency. Must differ from source_ccy. |
source_amount |
integer | Yes | Amount in the source currency, in minor units. For example, 10000 = 100.00 USD. |
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/sell?source_ccy=840&target_ccy=643&source_amount=10000' \
--header 'X-Api-Key: 00000000-0000-4000-8000-000000000000'
Response
{
"source_currency": "840",
"target_currency": "643",
"amount": 853846,
"source_to_base": 12210,
"base_to_target": 143,
"base_currency": "UZS"
}
Response parameters
| Parameter | Type | Description |
|---|---|---|
source_currency |
string | Numeric code of the source currency. |
target_currency |
string | Numeric code of the target currency. |
amount |
integer | Conversion result in minor units of target_currency. Equal to source_amount × source_to_base / base_to_target, 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(source_amount × source_to_base / base_to_target)
What this response means
The method does not create a transfer operation — it only calculates the amount based on the current rate.
What to do next
Use amount as the final amount to be received in target_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": "source_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.