# Платёжный процесс

> Проследите путь инвойса от создания и выбора актива до обнаружения платежа, подтверждения, истечения срока и итогового вебхука.

## Два способа принимать деньги

В Paymos два продукта приёма денег, и выбор между ними меняет форму интеграции:

| | Инвойс | Платёжный канал |
|---|---|---|
| Что это | Один запрос на оплату | Постоянный адрес приёма одного плательщика |
| Сумма | Фиксируется при создании | Отсутствует — зачисляется каждый депозит не ниже минимума токена |
| Срок | Есть | Нет |
| Адрес | Выводится под каждый инвойс | По одному постоянному адресу на сеть, никогда не передаётся другим |
| Финальное состояние | `paid`, `paid_over`, `underpaid`, `expired`, `cancelled` | Нет — канал принимает, пока вы его не заблокируете |
| Когда подходит | Оформление заказа, разовые платежи | Пополнение баланса, регулярное финансирование, счета вне системы |

Дальше на этой странице описан жизненный цикл инвойса. Ветку каналов см. в [Создании платёжного канала](/ru/docs/payment-channels/create.md): у самого канала жизненного цикла нет — он есть у каждого пришедшего депозита, и он гораздо короче: `confirming` → `confirmed`, с промежуточным `reorged`, если цепочка реорганизуется.

## Жизненный цикл

```mermaid
stateDiagram-v2
    direction LR
    [*] --> awaiting_client: оба потока
    awaiting_client --> awaiting_payment: токен подтверждён
    awaiting_client --> cancelled: отмена
    awaiting_client --> expired: таймаут
    awaiting_payment --> confirming: обнаружен
    awaiting_payment --> expired: таймаут
    awaiting_payment --> underpaid: недостаточный
    confirming --> paid
    confirming --> paid_over: переплата
    confirming --> underpaid_waiting: частичная
    underpaid_waiting --> paid
    underpaid_waiting --> underpaid: таймер истёк
    paid --> [*]
    paid_over --> [*]
    underpaid --> [*]
    expired --> [*]
    cancelled --> [*]
```

Инвойс заканчивается одним из терминальных статусов: `paid`, `paid_over`, `underpaid`, `expired` или `cancelled`. Большинство переходов порождают [событие вебхука](/ru/docs/webhooks/events.md) — какое именно, указано в таблице статусов ниже. Всё начиная с `confirming` шлёт событие. Два статуса до оплаты — нет: открытие в `awaiting_client` проходит молча, и обычный переход в `awaiting_payment`, когда страница оплаты подтвердила токен, тоже. Исключение одно, и оно идёт в обратную сторону: если глубокий реорг убрал все зачтённые переводы, инвойс откатывается в `awaiting_payment`, и вот этот откат событие `invoice.awaiting_payment` шлёт.

## Два потока создания

Оба потока стартуют одинаково. Инвойс создаётся в статусе `awaiting_client`, адреса за ним ещё нет. Различаются они только тем, что вы передаёте и сколько остаётся решить клиенту. Адрес выделяется — и инвойс уходит в `awaiting_payment` — в тот момент, когда на странице оплаты подтверждён токен.

**Прямой крипто-поток** — передайте `amount` + `currency` + `network`. `amount` — это сумма к оплате в криптовалюте, токен и сеть закреплены сразу. Решать клиенту нечего: страница оплаты подтверждает эту пару, и адрес выделяется тут же.

**Фиатный поток** — передайте `amount` + `currency` (без `network`). `amount` — фиатная сумма. Клиент выбирает токен и сеть на странице оплаты; в этот момент Paymos фиксирует обменный курс, назначает адрес и инвойс переходит в `awaiting_payment`. Зафиксированный курс возвращается на инвойсе как `payment.exchange_rate`, рядом с точной суммой в токене `payment.expected`.

Полный список фиатных кодов и токенов — в [Поддерживаемых валютах](/ru/docs/supported-currencies.md), тело запроса — в [Создании инвойса](/ru/docs/invoices/create.md).

## Статусы

| Статус | Описание | Событие вебхука |
|--------|----------|-----------------|
| `awaiting_client` | Стартовый статус любого инвойса — адреса нет, пока страница оплаты не подтвердит токен | — |
| `awaiting_payment` | Адрес назначен, ожидает перевод | на входе — ничего; `invoice.awaiting_payment` только при откате после реорга |
| `confirming` | Платёж обнаружен, ожидает подтверждений | `invoice.confirming` |
| `underpaid_waiting` | Получена частичная оплата, ожидает остаток | `invoice.underpaid_waiting` |
| `paid` | Платёж подтверждён полностью | `invoice.paid` |
| `paid_over` | Полученная сумма превышает ожидаемую (зачисляется полностью) | `invoice.paid_over` |
| `underpaid` | Закрыт с недостаточной оплатой | `invoice.underpaid` |
| `expired` | Таймер истёк без оплаты | `invoice.expired` |
| `cancelled` | Отменён мерчантом (только из `awaiting_client`) | `invoice.cancelled` |

## Отмена

Инвойс можно отменить только в `awaiting_client` — пока страница оплаты не подтвердила токен. Дальше адрес уже активен, а клиенту названа фиксированная сумма в конкретной сети, поэтому отмена невозможна.

## Таймауты и истечение

| Параметр | Значение |
|----------|----------|
| Срок действия инвойса | Один на всю платформу; в запросе на создание не задаётся |
| Порог недоплаты | Настраивается по проекту |
| Обработка переплаты | Зачисляется полностью |

Срок отсчитывается от создания инвойса, а когда токен и сеть подтверждены, начинается заново: `expires_at` переносится на полное окно от этого момента. Даже если клиент выбрал сеть перед самым дедлайном, на перевод у него остаётся всё окно. Раньше прежнего дедлайн не наступит, а переопределить длину срока нельзя ни на инвойсе, ни на проекте.

Он закрывает выбор, а не платёж. До дедлайна страница оплаты принимает токен и сеть, после — `confirm-payment` отвечает `410 Gone`; обратный отсчёт плательщик видит у себя на странице. Перевод, который к этому моменту уже виден в сети, доводится до конца: инвойс закроется как `paid`, `paid_over` или `underpaid`. Отправленный позже — нет.

Если клиент отправит меньше требуемой суммы до истечения инвойса, итоговый статус зависит от `allow_multiple_payments`:

:::dash-list
- `allow_multiple_payments: true` — статус становится `underpaid_waiting`, дополнительные платежи принимаются до истечения таймера
- `allow_multiple_payments: false` — единственный недостаточный платёж сразу закрывает инвойс в `underpaid`
:::

Если таймер истечёт в `underpaid_waiting`, финальный статус определяется по общей полученной сумме и политике недоплаты. Если отправлено больше ожидаемого — зачисляется полная сумма и статус становится `paid_over`.