Overview

The Currency API gives access to exchange rates from two sources:

Commercial rate of the partner bank (/rates, /cross-rate, /convert/*) — real exchange rates with a spread (sell/buy), for actually converting amounts.
Official rates of the Central Bank of the Republic of Uzbekistan — reference rates from the Central Bank of the Republic of Uzbekistan (source: cbu.uz). One quote per day, without a spread — for displaying the official rate, accounting, and reference purposes.

The integration must be connected in advance

Exchange rates are only available to a shop after the integration with the rates provider has been connected. Contact KVELL support to enable it for the desired X-Api-Key. Until the integration is connected, any method in this section returns 404 with code 20044.

Methods

Method	Path	Purpose
Exchange rate	`GET /v1/currency/rates`	Commercial bank rate to UZS (sell/buy) — for display in the UI.
Cross rate	`GET /v1/currency/cross-rate`	Commercial rate between two arbitrary currencies.
Conversion (sell)	`GET /v1/currency/convert/sell`	Calculates the receiving amount based on the source transfer amount.
Conversion (buy)	`GET /v1/currency/convert/buy`	Calculates the payment amount needed to receive a target amount in another currency.
CBU exchange rates (list)	`GET /v1/currency/cbu/rates`	All official CBU exchange rates for the current day (~75 currencies).
CBU exchange rate (single currency)	`GET /v1/currency/cbu/rate`	Official CBU exchange rate for a single currency.
SBP payout with conversion	`POST /v2/orders/payout/sbp`	Payout via SBP with automatic conversion of the amount into the shop's currency.
SBP payout feasibility check with conversion	`POST /v2/orders/payout/sbp/check`	Checks the details and pre-calculates the conversion result before an SBP payout.

Payouts in another currency

«SBP payout with conversion» and «SBP payout feasibility check with conversion» are methods of the payouts section («Making a payout via SBP» and «Checking SBP payout feasibility») that additionally use conversion from this section: the payout amount, passed in the source currency, is automatically recalculated into the shop's payout profile currency using the same rate as «Conversion (sell)».

Which method to choose

Show the rate in the UI → «Exchange rate».
Show the rate between two arbitrary currencies → «Cross rate».
Calculate the exact transfer or payment amount → «Conversion (sell)» or «Conversion (buy)». Don't multiply the rate from «Exchange rate»/«Cross rate» by the amount manually — the rate is rounded on the bank's side.
Official rate for accounting and reference → «CBU exchange rates» or «CBU exchange rate».

Sell vs. Buy: what's the difference

«Conversion (sell)» and «Conversion (buy)» calculate the same conversion in different directions:

Sell (forward) — the amount in the source currency is known: "I have source_amount in source_ccy, how much will I receive in target_ccy?".
Buy (reverse) — the amount in the target currency is known: "I want to receive target_amount in target_ccy, how much do I need to pay in source_ccy?".

Choose the method based on which amount is known in advance — the debit amount or the credit amount.

How the rate is calculated

«Cross rate» and both conversion methods calculate the result via the base currency UZS, rather than directly between source_ccy and target_ccy:

rate = source_to_base / base_to_target

where source_to_base is the rate of the source currency to UZS, and base_to_target is the rate of UZS to the target currency. Both values are returned in the response along with the result — if needed, recalculate the amount yourself without making another request.

Request headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop identifier.

The X-Signature signature is not required for methods in this section.

Currency codes

Currencies are passed as a numeric ISO 4217 code in string form, for example "840" for USD, rather than the letter code ("USD"). The base settlement currency is "860" (UZS).

As of publication, the following currencies are available:

Currency	ISO code	Status
UZS	`860`	base
USD	`840`	available
EUR	`978`	available
RUB	`643`	available
GBP	`826`	unavailable

The list may change

The set of available currencies depends on the rates provider and may change without notice. If the requested currency is temporarily unavailable, the method returns 404 with code 20099.

Rules:

The currency code is passed as a number in string form ("840"), not as a letter code ("USD").
In «Cross rate», «Conversion (sell)», and «Conversion (buy)», source_ccy and target_ccy must differ — otherwise the method returns 400.
«Exchange rate» and «Cross rate» return the commercial bank rate (with a spread); «CBU exchange rates»/«CBU exchange rate» return the official CBU rate (without a spread). These are different rates and do not match at any given moment.

Minor units

In the «Conversion (sell)» and «Conversion (buy)» methods, amounts are passed and returned in the minor unit of the currency — similar to kopecks for the ruble.

Currency	Minor unit	Example
USD	cent	100.00 USD = `10000`
EUR	cent	50.00 EUR = `5000`
RUB	kopeck	10 000.00 RUB = `1000000`
UZS	tiyin	1 000 000 UZS = `100000000`

Error codes

Errors are returned in the common KVELL format: {"errors": [{"code", "message"}]}.

Code	Description
`20044`	The integration with the rates provider is not configured for the shop.
`20098`	Request field validation error.
`20099`	Rates provider error, `message` is passed through unchanged. The response HTTP code matches the provider's response (`400`, `404`, `502`, or `503`).
`20000`	Internal KVELL error.