Инвойсы: статусы и жизненный цикл
| Статус | Значение | Финальный |
|---|---|---|
active | Ждёт оплаты | нет |
paying | Платёж найден в блоке, ждёт подтверждений | нет |
partially_paid | Подтверждена часть суммы, можно доплатить на тот же адрес | нет |
paid | Оплачен полностью | да |
overpaid | Оплачен с излишком: overpaid: true, overpaid_amount | да |
expired | Срок истёк без полной оплаты | да |
canceled | Отменён мерчантом | да |
active ──платёж в блоке──▶ paying ──подтверждён, хватает──▶ paid / overpaid
│ │
│ ├─подтверждён, не хватает──▶ partially_paid ──доплата──▶ paying
│ └─reorg, транзакция пропала──▶ active / partially_paid
├─DELETE──▶ canceled
└─срок истёк──▶ expired (partially_paid тоже истекает)Правила:
- Обнаружение. Watcher видит перевод на адрес инвойса. Если монета совпадает с
asset, а инвойс вactiveилиpartially_paid, инвойс переходит вpayingи уходитinvoice_paying. - Подтверждение. После
required_confirmationsподтверждений (TRON 19, TON и Solana 1, Simnet 3, от 5000 вдвое больше) сумма зачитывается вpaid_amount, баланс мерчанта пополняется. На mainnet платёж от порога AML (по умолчанию 1000) перед зачислением ждёт проверки адреса отправителя, если в развёртывании включён AML-провайдер. Пока проверка не прошла, инвойс остаётсяpayingиinvoice_paidне уходит: обычно это секунды, при недоступности провайдера дольше. Платёж с высоким риском замораживается до решения оператора:invoice_paidпридёт, только если оператор его зачислит. - Допуск недоплаты. Инвойс считается оплаченным, если
paid_amount ≥ pay_amount − допуск. Допуск задаётся в настройках приложения (по умолчанию 0.5 %, от 0 до 2 %), но не меньше 0.5 монеты, если он не нулевой. Пример: при допуске 0.5 % инвойс на 10 USDT закрывается платежом от 9.5 USDT. - Частичная оплата. Если подтверждено меньше нужного и других платежей в пути нет: при включённой в настройках «частичной оплате» (по умолчанию включена) статус
partially_paidи событиеinvoice_partially_paid, иначе инвойс возвращается вactive. Доплата идёт на тот же адрес. - Истечение. Expirer раз в 5 секунд закрывает открытые инвойсы с прошедшим
expires_at. Инвойс, у которого есть платёж в блоке без нужных подтверждений, ждёт этих подтверждений. При истечении частично оплаченного инвойса его поступления становятсяunmatched: деньги остаются на балансе мерчанта, возврат плательщику делается вручную. - Поздний платёж на адрес истёкшего инвойса. С настройкой «принимать просроченные» и в пределах 24 часов после
expires_atплатёж зачитывается в инвойс, пока его адрес не выдан другому инвойсу (по умолчанию через час после закрытия, см. правило 11). Если суммы хватает, инвойс переходит вpaidс событиемinvoice_paid. Если не хватает, статус остаётсяexpiredс событиемpayment_late. Без настройки или позже 24 часов платёж становитсяunmatchedс событиемpayment_late. - Чужая монета (например USDC на инвойс в USDT):
unmatched, событиеpayment_unexpected, статус инвойса не меняется. - Платёж на закрытый инвойс (
paid,overpaid,canceled):unmatched, событиеpayment_unexpected. - Комиссия с
unmatched. С каждого такого поступления берётся та же комиссия: 1 %, минимум 0.1. Остаток зачисляется на баланс мерчанта. Возвраты плательщикам не автоматические: мерчант делает их сам выводом. - Дубли. Поступление идентифицируется по
(сеть, txid, log_index), повторная обработка того же события ничего не меняет. - Повторное использование адреса. После закрытия инвойса (
paid,overpaid,expired,canceled) его адрес возвращается в пул через паузу: по умолчанию 1 час, точное значение задаёт оператор. Пока адрес не выдан следующему инвойсу, платежи на него относятся к вашему инвойсу по правилам 6 и 8. После выдачи платёж на этот адрес, равный сумме нового инвойса, считается его оплатой, а новый инвойс может принадлежать другому мерчанту. Платёж на другую сумму никому не зачисляется автоматически: его разбирает оператор шлюза и относит к вашему инвойсу вручную, это занимает время. Показывайте плательщику срок инвойса и создавайте новый инвойс для каждой оплаты.