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

Lifecycle

Инвойс заканчивается одним из терминальных статусов: paid, paid_over, underpaid, expired или cancelled. Большинство переходов порождают webhook-событие — какое именно, указано в таблице статусов ниже. Оба статуса до оплаты (awaiting_client, awaiting_payment) событий не шлют; всё начиная с confirming — шлёт.

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

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

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

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

См. Поддерживаемые валюты для полного списка фиатных кодов и токенов, и Создание инвойса для тела запроса.

Статусы

Статус	Описание	Webhook-событие
awaiting_client	Стартовый статус любого инвойса — адреса нет, пока страница оплаты не подтвердит токен	—
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 — пока страница оплаты не подтвердила токен. Дальше адрес уже активен, а клиенту названа фиксированная сумма в конкретной сети, поэтому отмена невозможна.

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

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

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

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

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