Convert currency amount (v2)
Convert an amount between currencies. Only `amount` is strictly required — all other parameters fall back to operator-configured AppConfig defaults when omitted. Tariff is resolved via a four-step chain: fx_tariff_id query param → customer's assigned tariff (when customer_id provided) → convert.default_tariff_id AppConfig → the active tariff marked is_default = TRUE. FX date resolution is owned by the FX module business-date lookup policy, so omitted dates anchor to the current business date and optional lookback may resolve the most recent stored rate within the configured prior calendar-day window.
/v2/fx/rates/convertQuery Parameters
Amount to convert in minor units (default). Use amount_unit=major for decimal units.
Unit of the amount parameter: 'minor' (default) for atomic units (e.g. 10000 = 100 EUR), 'major' for decimal units (e.g. 100.50)
Base currency code. Falls back to convert.default_base AppConfig entry (object format {"code":"EUR","precision":2}) when omitted.
Target currency code. Falls back to convert.default_target AppConfig entry when omitted.
Customer UUID. When provided, the customer's assigned FX tariff is used as a fallback if fx_tariff_id is not specified. Customer-specific pricing takes precedence over the system default tariff.
FX tariff UUID (highest priority). Falls back through: customer's tariff (when customer_id provided) → convert.default_tariff_id AppConfig → the active tariff marked is_default = TRUE.
Transaction type for fee-range matching (BUY/SELL). Falls back to convert.default_type AppConfig when omitted.
Rate type for exchange-rate quote lookup (BUY/SELL/MID). Defaults to MID when omitted.
Rate source/provider (e.g., SNB, EB, CRP, OER)
Lookup business date in YYYY-MM-DD format. When omitted, FX anchors lookup to the current business date in the configured timezone. If lookback is enabled, the returned currency_pair.date may be earlier than the anchor date.
Return indicative rate without fees (default: false).
When set, return all fees (total_fee, fee_range fixed_fee/min_fee/max_fee) in this currency instead of base currency
Response Body
application/json
curl -X GET "https://example.com/v2/fx/rates/convert?amount=0"{
"amount": {
"amount": "10923",
"currency": "USD",
"precision": 2
},
"total_fee": {
"amount": "10923",
"currency": "USD",
"precision": 2
},
"mid_rate": 1.0923,
"fee_range": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"fx_tariff_id": "f12d958c-c80c-4752-862c-9e0c09506488",
"min_range": 0,
"max_range": 1000,
"fixed_fee": 1.5,
"percent_fee": 0.5,
"min_fee": 1,
"max_fee": 10,
"method": "fixed",
"date_start": "2019-08-24T14:15:22Z",
"date_end": "2019-08-24T14:15:22Z"
},
"tariff": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Standard FX Tariff",
"description": "Standard foreign exchange tariff for retail customers",
"active": true,
"fallback_tariff_id": "uuid"
},
"currency_pair": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"base_currency": "CHF",
"target_currency": "USD",
"base_ccy_precision": 2,
"target_ccy_precision": 2,
"rate": 1.0923,
"type": "BUY",
"date": "2024-03-20",
"source": "SNB",
"rate_at": "2019-08-24T14:15:22Z",
"imported_at": "2019-08-24T14:15:22Z"
},
"spread_rule_id": "82788b45-8d95-4a1a-86a2-bb04e0f38547",
"applied_rule_ids": [
"82788b45-8d95-4a1a-86a2-bb04e0f38547",
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
],
"fallback_tariff_used": false,
"fallback_tariff_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}