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

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

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

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

Дальше на этой странице описан жизненный цикл инвойса. Ветку каналов см. в Создании платёжного канала: у самого канала жизненного цикла нет — он есть у каждого пришедшего депозита, и он гораздо короче: confirming → confirmed, с промежуточным reorged, если цепочка реорганизуется.

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

Инвойс заканчивается одним из терминальных статусов: paid, paid_over, underpaid, expired или cancelled. Большинство переходов порождают событие вебхука — какое именно, указано в таблице статусов ниже. Всё начиная с 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.

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

Статусы

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

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

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

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

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

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

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

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