Skip to content

Cross rate

Returns the commercial cross rate between two arbitrary currencies, calculated via the base currency (UZS). Use this to display the cross rate; for an exact conversion amount calculation, use «Conversion (sell)» or «Conversion (buy)».

URL

GET https://api.pay.kvell.group/v1/currency/cross-rate

GET https://api.pay.stage.kvell.group/v1/currency/cross-rate

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.

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/cross-rate?source_ccy=840&target_ccy=643' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000'

Response

Example 200 (OK) response
{
  "source_currency": "840",
  "target_currency": "643",
  "rate": 85.3846,
  "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.
rate number Units of target_currency per 1 unit of source_currency. Equal to source_to_base / base_to_target.
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

rate = source_to_base / base_to_target

What this response means

The rate is current as of the response and may change on the next request.

What to do next

Use rate to display the cross rate. For an exact transfer amount calculation, use «Conversion (sell)» or «Conversion (buy)».

Example 400 (Bad Request) response
{
  "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 — a cross rate of a currency to itself makes no sense.

What to do next

Pass two different currency codes and retry the request.

Example 404 (Not Found) response
{
  "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 not connected; 20099 — the rate for one of the currencies is unavailable from the provider.
errors[].message string Description of the reason.

What this response means

For code 20044, contact KVELL support to connect the integration with the rates provider. 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.

Example 422 (Unprocessable Entity) response
{
  "errors": [
    {
      "code": 20098,
      "message": "target_ccy: Field required"
    }
  ]
}

Response parameters

Parameter Type Description
errors array List of validation errors.
errors[].code integer Error code.
errors[].message string Field and reason for the validation error.

What this response means

A required parameter was not passed, or it does not match the expected format.

What to do next

Fix the field from errors[].message and retry the request.

Example 5XX (Internal Server Error) response
{
  "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 is read-only and changes nothing — a technical error cannot lead to an indeterminate result.

What to do next

Safely retry the same request. If the error persists, contact KVELL support and provide the URL, request time, HTTP code, code, and message.