Payment Orchestrator

Тема

03.09 FX, Currency Conversion And Fees ​

Статус: черновик для обсуждения

1. Назначение документа ​

Этот документ описывает, как в MVP должны работать:

  • currency conversion;
  • conversion fee;
  • processing fee;
  • сохранение FX / fee данных в transaction;
  • visibility FX / fee данных для platform users, merchant users и customer.

2. Основные принципы ​

В системе есть два разных типа fee:

  • processing fee;
  • conversion fee.

Они относятся к разным уровням routing hierarchy и оплачиваются разными сторонами.

Processing fee относится к финансовым условиям между platform и merchant. Conversion fee относится к customer amount при currency conversion.

3. Processing fee ​

Processing fee настраивается на уровне:

text
MASTER MID

Processing fee применяется ко всем transactions, которые проходят через этот MASTER MID.

Processing fee оплачивает merchant.

Processing fee не должна менять сумму, которую платит customer.

То есть:

  • customer amount остается customer-facing суммой;
  • processing fee используется для расчетов / settlement / merchant cost;
  • provider request amount не должен увеличиваться из-за processing fee.

4. Processing fee calculation types ​

Processing fee должна поддерживать все основные варианты расчета:

  • fixed amount;
  • percent;
  • fixed amount + percent;
  • min cap;
  • max cap;
  • thresholds / tiers by MASTER MID turnover.

Пример:

text
Processing fee:
- 1.5%
- + 0.20 EUR fixed
- min 0.50 EUR
- max 10.00 EUR

Точный UI для настройки fee должен быть описан в Back Office configuration document.

Processing fee thresholds ​

Processing fee должна поддерживать thresholds по обороту через весь MASTER MID.

Thresholds настраиваются в EUR.

Пример:

text
MASTER MID turnover 0 - 100,000 EUR:
- 2.0%
- + 0.30 EUR fixed

MASTER MID turnover 100,000 - 1,000,000 EUR:
- 1.5%
- + 0.20 EUR fixed

MASTER MID turnover 1,000,000 EUR - infinity:
- 1.0%
- + 0.10 EUR fixed

Для каждого threshold/tier можно настроить:

  • fixed amount;
  • percent;
  • fixed amount + percent;
  • min cap;
  • max cap.

Система должна определить applicable threshold на основании оборота через MASTER MID в EUR.

Turnover period:

text
calendar month

В turnover для threshold входят только transactions в status:

text
COMPLETED

Threshold выбирается на момент provider request.

После выбора threshold/tier для transaction он сохраняется в transaction snapshot и не меняется для этой transaction.

Current transaction amount не должен учитываться при выборе threshold для самой этой transaction.

Система должна смотреть на completed turnover через MASTER MID до текущей transaction.

Boundary behavior:

  • если turnover находится ровно на границе threshold, transaction считается на текущем уровне;
  • следующий threshold не применяется только из-за того, что current transaction может перевести оборот за границу;
  • current transaction amount не учитывается при выборе tier.

Пример:

text
Tier 1: 0 - 100,000 EUR
Tier 2: 100,000 - 1,000,000 EUR

Completed turnover before current transaction: 100,000 EUR
Current transaction amount: 1,000 EUR

Applicable tier for current transaction: Tier 1

Если manual correction меняет status transaction на COMPLETED, transaction должна быть добавлена в monthly MASTER MID turnover.

Если transaction была COMPLETED, а потом manual correction изменила ее final status на не-COMPLETED, turnover for threshold calculation должен быть пересчитан.

Processing fee currency ​

В UI processing fee values задаются в EUR.

Если transaction original currency не EUR:

  1. Система рассчитывает processing fee в EUR.
  2. Система переводит processing fee в original transaction currency.
  3. Transaction сохраняет processing fee snapshot в EUR and original currency.

Processing fee не увеличивает customer amount and provider request amount.

5. Conversion fee ​

Conversion fee настраивается на уровне:

text
SUB MID
SUB MID AGGREGATOR

Conversion fee оплачивает customer.

Conversion fee добавляется сверху к сумме customer.

Это значит:

text
Original customer amount: 100 USD
Conversion fee: 2 USD
Final customer amount: 102 USD

Conversion fee не должна быть скрыто включена только в exchange rate. Система должна хранить conversion fee отдельно, чтобы ее можно было отобразить и расследовать.

Conversion fee должна поддерживать те же основные calculation types:

  • fixed amount;
  • percent;
  • fixed amount + percent;
  • min cap;
  • max cap.

В UI conversion fee values задаются в EUR.

Если transaction original currency не EUR, система переводит configured/calculated conversion fee в original transaction currency перед provider request.

6. Когда фиксируется FX rate ​

FX rate фиксируется перед provider request.

FX rate берется из нашего internal FX service.

Причина:

  • routing может выбрать разные SUB MID / SUB MID AGGREGATOR;
  • разные provider configurations могут иметь разные currency requirements;
  • dynamic customer attributes могут дособираться на hosted payment form;
  • финальная provider execution configuration становится известна только перед отправкой request в provider.

До provider request система может использовать estimated / calculated EUR equivalent для routing и velocity checks, но финальный FX snapshot должен быть сохранен перед provider request.

7. Что нужно сохранить в transaction ​

Transaction должна сохранять полный FX / fee snapshot.

Минимально нужно сохранить:

  • original amount;
  • original currency;
  • base currency;
  • base amount;
  • provider amount;
  • provider currency;
  • FX rate;
  • FX rate timestamp;
  • conversion fee amount;
  • conversion fee currency;
  • conversion fee amount in EUR;
  • conversion fee amount in original currency;
  • final customer amount;
  • processing fee amount;
  • processing fee currency;
  • processing fee amount in EUR;
  • processing fee amount in original currency;
  • processing fee calculation details;
  • processing fee threshold/tier used;
  • MASTER MID turnover value used for threshold selection;
  • MASTER MID, через который применена processing fee;
  • SUB MID / SUB MID AGGREGATOR, через который применена conversion fee.

Base currency для системы:

text
EUR

8. Original amount, base amount, provider amount ​

Система должна различать:

  • original amount/currency: сумма и валюта, которые пришли от merchant;
  • base amount/currency: сумма, приведенная к EUR для внутренних расчетов;
  • provider amount/currency: сумма и валюта, которые отправляются в provider;
  • final customer amount: сумма, которую должен оплатить customer с учетом conversion fee;
  • conversion fee EUR/original currency: customer fee snapshot;
  • processing fee EUR/original currency: merchant cost snapshot, который не влияет на customer amount.

Пример:

text
Merchant request:
amount: 100
currency: USD

Base:
amount: 95.05
currency: EUR

Conversion fee:
amount: 2
currency: EUR

Final customer amount:
amount: 102.35
currency: USD

Provider request:
amount: 102.35
currency: USD

Точный расчет зависит от selected SUB MID / SUB MID AGGREGATOR configuration.

9. Кто может настраивать FX / conversion fee ​

Если SUB MID создан platform user:

  • FX / conversion fee может настраивать только platform user с permission.

Если SUB MID создан merchant user:

  • FX / conversion fee может настраивать merchant user с permission;
  • FX / conversion fee может настраивать platform user с permission.

SUB MID AGGREGATOR является platform-level configuration. FX / conversion fee на SUB MID AGGREGATOR может настраивать только platform user с permission.

10. Visibility для merchant users ​

Merchant user с permission должен видеть FX / conversion fee на transaction details.

Merchant user может видеть:

  • original amount/currency;
  • base amount/currency;
  • provider amount/currency, если visibility rules позволяют;
  • FX rate;
  • conversion fee;
  • final customer amount;
  • processing fee, если permission позволяет;
  • processing fee threshold/tier used, если permission позволяет;
  • fee calculation summary.

Если transaction прошла через platform-hidden SUB MID / SUB MID AGGREGATOR, merchant user не должен видеть hidden provider/internal configuration details.

При этом merchant user должен понимать финансовый результат transaction.

11. Visibility для platform users ​

Platform user с permission должен видеть полный FX / fee snapshot.

Platform user может видеть:

  • all merchant-visible fields;
  • exact MASTER MID processing fee configuration;
  • exact MASTER MID processing fee thresholds;
  • exact SUB MID / SUB MID AGGREGATOR conversion fee configuration;
  • internal FX service rate/source data;
  • full calculation breakdown;
  • rounding details;
  • provider amount/currency;
  • internal configuration references.

12. Visibility для customer ​

В MVP customer на hosted payment form не видит conversion fee отдельно.

Customer не должен видеть:

  • conversion fee breakdown;
  • FX rate;
  • processing fee;
  • provider/internal details.

Customer-facing UX в MVP должен быть максимально простым.

Если в будущем потребуется показывать customer final amount / fee breakdown, это должно быть описано отдельно как расширение hosted payment form.

13. Rounding ​

Точный rounding mode должен быть предложен development team.

Product requirement:

  • система должна хранить calculation details;
  • rounding должен быть deterministic;
  • rounding должен быть одинаковым для одинаковых inputs;
  • rounding должен быть виден platform user с permission;
  • спорные cases должны быть воспроизводимы через transaction details / timeline.

14. Timeline events ​

Transaction timeline должна фиксировать FX / fee события.

Минимально:

  • FX calculation started;
  • FX rate selected;
  • conversion fee calculated;
  • processing fee calculated;
  • processing fee threshold selected;
  • provider amount calculated;
  • FX / fee snapshot saved.

Merchant-safe timeline может показывать simplified summary.

Platform timeline должна показывать full calculation details.

15. Audit log ​

Любые изменения FX / fee configuration должны попадать в audit log.

Audit log должен фиксировать:

  • кто изменил configuration;
  • когда изменил;
  • какую сущность изменил;
  • old value;
  • new value;
  • affected MASTER MID / SUB MID / SUB MID AGGREGATOR;
  • context: platform / merchant.

16. Acceptance Criteria ​

FX / Currency Conversion / Fees считаются реализованными для MVP, если:

  • Processing fee настраивается на MASTER MID.
  • Processing fee не меняет customer amount.
  • Processing fee поддерживает fixed amount.
  • Processing fee поддерживает percent.
  • Processing fee поддерживает fixed + percent.
  • Processing fee поддерживает min/max cap.
  • Processing fee поддерживает thresholds / tiers by MASTER MID turnover.
  • Processing fee threshold turnover period is calendar month.
  • Processing fee threshold turnover includes only COMPLETED transactions.
  • Processing fee threshold is selected before provider request and saved in transaction snapshot.
  • Current transaction amount is not included when selecting its own processing fee threshold.
  • If transaction is manually corrected to COMPLETED, it must be added to monthly MASTER MID turnover.
  • If COMPLETED transaction is manually corrected to non-COMPLETED, MASTER MID turnover must be recalculated.
  • Processing fee values в UI задаются в EUR.
  • Processing fee рассчитывается в EUR and converted to original transaction currency.
  • Conversion fee настраивается на SUB MID / SUB MID AGGREGATOR.
  • Conversion fee оплачивает customer.
  • Conversion fee добавляется сверху к customer amount.
  • Conversion fee поддерживает fixed amount.
  • Conversion fee поддерживает percent.
  • Conversion fee поддерживает fixed + percent.
  • Conversion fee поддерживает min/max cap.
  • Conversion fee values в UI задаются в EUR.
  • Conversion fee рассчитывается в EUR and converted to original transaction currency.
  • FX rate фиксируется перед provider request.
  • FX rate берется из internal FX service.
  • Transaction сохраняет original amount/currency.
  • Transaction сохраняет base amount/currency в EUR.
  • Transaction сохраняет provider amount/currency.
  • Transaction сохраняет FX rate.
  • Transaction сохраняет conversion fee.
  • Transaction сохраняет conversion fee in EUR and original transaction currency.
  • Transaction сохраняет final customer amount.
  • Transaction сохраняет processing fee.
  • Transaction сохраняет processing fee threshold/tier used.
  • Transaction сохраняет original amount, converted/base amount, FX rate, conversion fee amount and processing fee amount.
  • Merchant user с permission видит FX / conversion fee на transaction details.
  • Merchant user с permission видит processing fee на transaction details.
  • Customer в MVP не видит conversion fee отдельно.
  • Customer в MVP не видит fee breakdown.
  • Platform user с permission видит полный FX / fee snapshot.
  • Изменения FX / fee configuration пишутся в audit log.