Мультивалютні книги та курси

1) Що таке «мультивалютні книги»

• Wallet-книга: рахунок гравця (ігрова валюта/валюти).
• Settlement-книга: розрахунки з PSP/еквайром (валюта сеттлменту).
• Treasury-книга: банківські рахунки, конвертації, хедж-угоди.
• Reporting-книга: звід у звітній валюті (наприклад, EUR) без ретроспективної переоцінки продуктових метрик.

Кожна книга фіксує валюту операції, валюту подання і курс на момент визнання.

2) Ієрархія валют і політик

1. Base/Reporting Currency - єдина звітна валюта (наприклад, EUR).
2. Wallet Currencies - валюти гаманців (USD/EUR/TRY/UAH тощо).
3. Settlement Currencies - що надсилає PSP (наприклад, USD).
4. Bank Currencies - валюта рахунку мерчанта/казначейства.

• Продуктові метрики (ND/NGR/ARPPU) - за історичним курсом події (зазвичай'settled _ at').
• Фінанси/трежери - додатково фіксують курс на'funded _ at'і'payout _ at'.
• Заборонена «прихована» переоцінка в продуктових вітринах.

3) Курси та їх джерела

Intraday reference (tick/minute): Refinitiv/ECB/банки - для нормалізації подій.
EOD (кінець дня): для переоцінки залишків (unrealized FX).
Effective FX: з файлу PSP/банку (факт конвертації).
Triangulation: через якір (EUR або USD) при відсутності прямого котирування.
Quote policy: `mid` либо `bid/ask` → `mid ± spread_bps`. Спред зберігається окремо.

Зберігайте: `fx_source`, `fx_pair`, `fx_rate`, `fx_timestamp`, `quote_type`, `spread_bps`, и маршрут triangulation.

4) Точки визнання і шари курсів

'authorize _ at'- курс не фіксуємо (без захоплення немає визнання).
'captured/settled _ at'- історичний курс для продуктового шару і ND.
«funded _ at» - курс вступу на банк (realized FX для FI/treasury).
'payout _ at'- курс при виплаті гравцеві.
«eod» - курс кінця дня для переоцінки залишків (unrealized FX).

5) Точність, округлення, мінімальні одиниці

Гроші - цілі minor units (int) +'scale'в довіднику валют.
Курси - не менше 8-10 знаків після коми.
Округлення: банківське (half-even) для звітності; в UI - локальні правила.
Вести роздільні поля: `amount_original`, `amount_wallet`, `amount_reporting`, `amount_effective`.

6) Подвійний запис і GL-карта (спрощено)

6. 1. DEPOSIT_CAPTURED (GBP, звітна - EUR)

Дт: AR: PSP (GBP)

Кт: Player Balance (GBP/EUR за гаманцем)

Паралельно фіксуємо'fx _ rate _ settle (GBP→EUR)'і'amount _ reporting'.

6. 2. FUNDING_RECEIVED (USD на банк)

Дт: Bank USD

Кт: AR: PSP GBP (закриваємо по еквіваленту; різниця → Realized FX).

6. 3. WITHDRAWAL_PAID (TRY)

Дт: Liability: Player (TRY)

Кт: Bank TRY (або Bank EUR + конвертація; різниця - realized FX).

7) Архітектура даних (мінімальна модель)

ref. currencies (
code PK, scale, symbol, is_crypto, is_active
)

ref. fx_rates_intraday (
pair PK, ts PK, rate, quote_type, source, spread_bps, triangulation_meta
)

ref. fx_rates_eod (
pair PK, date PK, rate, source
)

ledger. entries (
entry_id PK, book, -- WALLET      SETTLEMENT      TREASURY      REPORTING debit_account, credit_account,
amount_original, currency_original,
amount_reporting, reporting_currency,
fx_rate_at_settle, fx_source, fx_pair, fx_timestamp,
event_type, event_id, user_id, provider, method,
occurred_at, created_at, meta
)

treasury. funding_receipts (
funding_id PK, provider, bank_account,
currency, amount, fx_to_reporting, amount_reporting,
received_at, value_date, meta
)

treasury. balances (
date PK, account PK, currency PK, amount
)

dw. transactions_flat (
tx_id PK, user_id, provider, method, type, status,
amount_original, currency_original,
amount_reporting, reporting_currency, fx_rate_at_settle,
settled_at, funded_at, conversion_owner, meta
)

8) Потік нормалізації (ETL/ELT)

1. Інгест сировини → нормалізація статусів PSP.
2. Присвоєння історичного курсу на'settled _ at'з'fx _ rates _ intraday'.
3. Запис подвійної проводки в потрібну книгу (wallet/settlement).
4. Окремий імпорт funding і effective FX.
5. Щоденна reval залишків по'fx _ rates _ eod'( treasury-книга).
6. Побудова вітрин (ND/NGR/LTV) без ретро-переоцінки.

9) Звірка і консистентність

Tx→File: всі captured/settled потрапили у файл PSP (за сумами/валютами/датами).
File→Tx: все у файлі відображено в книгах/проводках.
FX Reference vs Effective: вважати'slippage _ bps'; алерт на вихід за поріг.
Перевірка triangulation: «A→B B→C» ≈ «A→C» в межах bps-толерансу.
Ідемпотентність: 'event _ id'і'idempotency _ key'- захист від дублів.

10) Часті сценарії і як їх вести

Multi-wallet: гаманець гравця може бути в іншій валюті, ніж депозит - робіть внутрішню конвертацію за вашим курсом (політика'conversion _ owner ='MERCHANT ").
PSP-conversion: зберігайте'fx _ effective','fx _ reference'і'spread _ bps'для аналізу маржі PSP.
Крипто: оцінка по VWAP-вікну; funding в стейблах - другий шар FX.
Cross-wallet transfer: рух всередині платформи - без FX-доходу, просто перенесення між книгами.

11) SQL-шаблони

11. 1. Нормалізація суми у звітну валюту за історичним курсом

sql
SELECT t. tx_id,
t. amount_original,
t. currency_original,
r. rate AS fx_rate_at_settle,
ROUND(t. amount_original r. rate, rep. scale) AS amount_reporting
FROM raw. transactions t
JOIN ref. fx_rates_intraday r
ON r. pair = CONCAT(t. currency_original, '/',:reporting_ccy)
AND r. ts = (
SELECT MAX(ts) FROM ref. fx_rates_intraday
WHERE pair = r. pair AND ts <= t. settled_at
)
JOIN ref. currencies rep ON rep. code =:reporting_ccy
WHERE t. settled_at BETWEEN:from AND:to;

11. 2. Вимірювання спреду PSP (effective vs reference)

sql
SELECT provider, method, DATE(settled_at) AS d,
SUM(original_amount fx_reference_rate) AS ref_in_reporting,
SUM(settlement_amount_in_reporting)   AS eff_in_reporting,
10000 (SUM(settlement_amount_in_reporting) /
NULLIF(SUM(original_amount fx_reference_rate),0) - 1) AS spread_bps
FROM dw. fx_settlement_view
WHERE settled_at BETWEEN:from AND:to
GROUP BY 1,2,3;

11. 3. Переоцінка залишків EOD (unrealized FX)

sql
INSERT INTO treasury. fx_reval_ledger (date, currency, position_amount, rate_eod, amount_reporting_eod, reval_diff, type)
SELECT
:eod AS date, b. currency, b. amount,
e. rate AS rate_eod,
b. amount e. rate AS amount_reporting_eod,
b. amount (e. rate - COALESCE(l. rate_eod, e. rate)) AS reval_diff,
'UNREALIZED'
FROM treasury. balances b
JOIN ref. fx_rates_eod e
ON e. pair = CONCAT(b. currency, '/',:reporting_ccy) AND e. date =:eod
LEFT JOIN LATERAL (
SELECT rate_eod FROM treasury. fx_reval_ledger
WHERE currency=b. currency AND date=:eod - INTERVAL '1 day'
ORDER BY date DESC LIMIT 1
) l ON TRUE;

12) KPI і дашборди

FX Slippage (bps) за PSP/методом/MID.
Realized FX P&L (funding/payout) и Unrealized FX (EOD/EOM).
Open FX Position по валютах vs ліміти політики.
Hit-rate «вчасно отриманих» курсів (stale-rates інциденти).
Частка PSP-conversion vs Merchant-conversion і її TCO.
Точність округлень (відхилення сум ≥ 1 minor unit - прапор).

13) Алерти і пороги

Stale rate: немає курсу на момент події → fallback-джерело/ретрай.
Triangulation mismatch: розбіжність> X bps.
Spread spike: 'spread _ bps'вище порогу за мажорами/мейнерами.
Open position breach: перевищення ліміту по будь-якій валюті.
Reval shock: денна переоцінка <−Xσ або> + X σ - рев'ю.

14) Best practices (коротко)

1. Строго розділяйте продуктовий шар (історичний FX) і FI/treasury (funding/payout/reval).
2. Використовуйте minor units і зберігайте курси з високою точністю.
3. Логуйте conversion_owner та вимірюйте маржу PSP (effective vs reference).
4. Реалізуйте ідемпотентність подій і двосторонню звірку (Tx→File і File→Tx).
5. Тримайте anchor-валюту для triangulation і валідуйте розбіжності в bps.
6. Переоцінку залишків робіть EOD-процедурою з окремим GL.
7. Враховуйте DST/таймзони при присвоєнні курсів на settle/funding.
8. Регулярно тестуйте округлення (property-based tests на кордонах scale).

15) Чек-лист впровадження

• Визначена reporting currency і політика історичного FX.
• Джерела курсів: intraday + EOD, fallback і SLA оновлення.
• Моделі'ledger. entries`, `fx_rates_`, `funding_receipts`, `balances`, витрина `transactions_flat`.
• Механізм triangulation і лог маршруту.
• Альберти: stale-rates, spread spike, triangulation mismatch, open position breach.
• Дашборди KPI і акти звірки з PSP/банком.
• Процедури reval і роздільні GL для realized/unrealized FX.
• Тест-набори округлень і точності зберігань.

Резюме

Мультивалютні книги - це дисципліна поділу шарів: історичний FX для продукту, фактичний для трежері, EOD-переоцінка для балансів. З прозорими джерелами курсів, точною моделлю даних, подвійним записом і автоматизованою звіркою ви виключите «валютний шум» з аналітики, забезпечите аудит і отримаєте керований FX-ризик при глобальній монетизації.