> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing и accounting — краткое резюме

> **Аудитория**: CFO, COO, владельцы платформы\
> **Цель**: согласовать billing-модель, коммерческие условия и операционные процессы\
> **Статус**: концепт на этапе review, до реализации\
> **Техническая документация**: `BILLING.md`, для команды разработки

## 1. Что такое billing-модуль

PostCash - это платформа для выпуска и распространения цифровых чеков, то есть prepaid-инструментов, в USDC. Billing-модуль отвечает за сквозной учет финансовых потоков внутри платформы: от сбора merchant fees до выставления инвойсов операторам инстансов и генерации settlement-документов для distribution-отношений.

У модуля три основные задачи:

1. **Accounting** - каждая комиссия, начисленная и собранная платформой, записывается в неизменяемый ledger.
2. **Invoicing** - операторам инстансов выставляются ежемесячные invoices за использование инфраструктуры.
3. **Merchant settlements** - для distribution-транзакций формируются agency reports и settlement-документы.

## 2. Бизнес-модель: источники выручки платформы

Платформа генерирует выручку на двух уровнях.

### Уровень 1 — Infrastructure fees, уже реализованы

Платформа взимает комиссию за каждый выпущенный чек. Комиссия автоматически списывается с кошелька merchant в момент, когда чек фондируется.

| Тип комиссии | С кого списывается | Как собирается |
| :- | :- | :- |
| Issuance fee | Merchant | Автоматически собирается при фондировании чека, через блокчейн |
| Redemption fee | Recipient | Удерживается из номинала чека в момент redemption |
| Exchange markup | Recipient | Встроена в FX rate |
| Fiat on-ramp fee | Recipient | Добавляется к сумме банковского перевода |

Тарифные планы настраиваются отдельно для каждого merchant через систему fee tiers. Базовая ставка по умолчанию составляет 2% плюс фиксированная часть, с минимумом 0.25 USDC на один чек.

### Уровень 2 — Distribution model, agency-структура

Оператор инстанса, то есть Issuer, распространяет физические batch-партии чеков через merchant-дистрибьюторов. В этой модели чек рассматривается как продукт с номиналом.

**Ключевые принципы модели:**

* Merchant принимает batch чеков **на реализацию**, а не выкупает его полностью.
* Merchant продает чек конечному клиенту и сразу **активирует** его, например в точке продаж.
* Merchant рассчитывается с Issuer по номиналу активированных чеков **один раз за settlement-период**, обычно ежемесячно.
* Нефондированные или непроданные чеки, не реализованные в течение допустимого срока, **возвращаются**, а обязательство merchant аннулируется.

## 3. Distribution model: экономика merchant

### Структура вознаграждения merchant

Merchant получает доход в двух формах, которые намеренно разделены для целей налоговой оптимизации.

**Форма 1 — Agency commission, upfront и оплачивается клиентом**

Merchant добавляет небольшую наценку к номиналу чека при продаже конечному клиенту. Это и есть декларируемая выручка merchant и его налогооблагаемая база.

*Пример:* чек на \$100 USDC → клиент платит €92.46, по FX-курсу плюс наценка 0.5% → merchant перечисляет €92.00 Issuer и оставляет себе €0.46.

**Форма 2 — Retroactive bonus, post-settlement и выплачивается Issuer**

После успешного settlement за период Issuer выплачивает merchant бонус, основанный на объеме подтвержденных транзакций. Такой бонус является выплатой от иностранного юридического лица и обычно подпадает под более выгодный налоговый режим.

*Пример:* settled volume \$10,000 USDC → бонус 1.5% → \$150 USDC.

**Совокупная экономика merchant:**

| Item | Amount |
| :- | :- |
| Cheques sold | 100 × \$100 = \$10,000 USDC |
| Collected from customers | €9,246 (at FX rate + 0.5%) |
| Remitted to Issuer | €9,200 |
| Agency commission | €46 (declared revenue) |
| Retroactive bonus | \$150 USDC |
| **Total merchant income** | эквивалент \~\$200, около 2.0% оборота |
| **Taxable base** | €46, только agency commission |

### Юридическая структура

Модель строится как **agency agreement**, где principal - это Issuer, а agent - Merchant.

* Merchant продает **от имени Issuer**, а не от собственного имени.
* Выручка merchant равна только agency commission, а не полной цене продажи.
* Issuer зарегистрирован в офшорной юрисдикции, например UAE, BVI или Singapore, и не является налоговым резидентом стран, в которых работает merchant.
* Это трансграничная B2B-модель поставки: VAT в юрисдикции merchant применяется только к agency commission по механизму reverse charge.
* **Merchant полностью отвечает за собственное локальное налоговое соответствие.** Платформа не несет за это ответственности.

## 4. Поток документов

### Уровень платформы, Platform → Instance Operator

| Документ | Содержимое | Частота |
| :- | :- | :- |
| **Platform invoice** | Общие инфраструктурные комиссии за месяц | Ежемесячно |
| **Fee ledger extract** | Детализация по транзакциям | По запросу / CSV |

Статусы invoice: `Draft → Issued → Paid / Overdue / Voided`

### Уровень distribution, Issuer ↔ Merchant

| Документ | Кто готовит | Содержимое |
| :- | :- | :- |
| **Settlement statement** | Issuer → Merchant | Сумма к оплате за активированные чеки за период |
| **Agency report** | Merchant → Issuer | Отчет о продажах и перечисленных суммах |
| **Bonus notice** | Issuer → Merchant | Сумма retroactive bonus к выплате |

## 5. Billing modes

Платформа поддерживает два режима сбора комиссий.

| Mode | Description | Status |
| :- | :- | :- |
| **Automatic, on-chain** | Комиссии собираются сразу по каждой транзакции через блокчейн | Live |
| **Invoice-based** | Комиссии накапливаются и выставляются раз в месяц | Planned |

Режим настраивается отдельно для каждого instance. Invoice-based billing предназначен для крупных merchants с налаженными settlement-процессами, чтобы не было необходимости постоянно держать средства в кошельке платформы.

## 6. Контроль доступа

У каждой billing-функции есть настраиваемый уровень доступа. Права назначаются по ролям.

**Роли уровня платформы**: `Owner`, `Administrator`, `Finance`, `Developer`\
**Роли уровня instance**: `Owner`, `Administrator`, `Finance`, `Viewer`

**Принцип по умолчанию**: роль **Finance** имеет полный доступ ко всем billing-функциям. Администраторы могут выборочно ограничивать или расширять доступ к каждой функции через редактор permissions.

**Финансовые действия, требующие повторной аутентификации**, то есть дополнительного подтверждения через passkey:

* Invoice finalization and voiding
* Payment confirmation
* Changes to merchant credit limits
* Changes to merchant credit rating
* Manual credit freeze / unfreeze

## 7. Controls и compliance

### Неизменяемость финансовых записей

Fee ledger является **append-only**. Исторические записи нельзя изменять или удалять. Это обеспечивает целостность финансовой истории и поддерживает требования аудита.

### Audit trail

Каждое административное действие, затрагивающее финансовые данные, логируется: кто внес изменение, когда это произошло, что именно изменилось и как выглядели значения до и после. Сам лог не редактируется.

### Reconciliation

Платформа формирует ежемесячные reconciliation snapshots, чтобы сравнивать фактически собранные комиссии с ожидаемыми. Любые расхождения помечаются для ручной проверки.

## 8. Текущий статус реализации

| Функция | Статус |
| :- | :- |
| On-chain fee collection | Live |
| Fee ledger | Live |
| Invoices (generation, draft, issuing) | Basic version live |
| PDF invoice | In development |
| Invoice email delivery | In development |
| Invoice payment confirmation | In development |
| Invoice-based billing mode | In development |
| Merchant settlement documents | Planned |
| Bonus notices | Planned |
| CSV export for accounting | Live |

## 9. Открытые вопросы на согласование

**9.1 Pricing plans**\
Согласованы ли базовые комиссии, то есть 2% + 0.25 USDC по умолчанию? Нужны ли специальные условия для отдельных категорий merchant?

**9.2 Settlement period**\
Стандартный период составляет 30 дней. Нужно ли поддерживать исключения для крупных партнеров?

**9.3 Retroactive bonus rates**\
Какая базовая bonus rate должна использоваться и какие volume tiers нужны для более высоких rebate? В текущем черновике предполагается 1.5% и порог \$50k в месяц.

**9.4 Payment delinquency**\
Что считать overdue? Какой должен быть порядок взыскания? Нужно ли автоматически блокировать отгрузку новых batch-партий чеков?

**9.5 Issuer jurisdiction**\
Подтверждена ли юрисдикция регистрации Issuer? Это влияет на юридическую структуру agency agreements.

**9.6 Settlement currency**\
В каких валютах merchants будут рассчитываться с Issuer? Кто устанавливает FX rate и на какую дату он фиксируется?


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.