Недоплата, переплата и автовозврат

В крипте покупатель почти никогда не отправляет ровно ту сумму, что вы выставили: комиссия сети, округление в кошельке, задержка курса. Oblodai даёт две настройки, которые определяют, что считать успешной оплатой и что делать с расхождением: допуск (accuracy) и автовозврат (autorefund).

---

​

Две настройки, две разные задачи

Настройка	Отвечает на вопрос	Метод
accuracy (допуск)	«Какое отклонение от суммы всё ещё считать оплатой?»	/v1/payment/accuracy
autorefund (автовозврат)	«Что вернуть, если платёж вышел за допуск?»	/v1/payment/autorefund

Они работают вместе: сначала accuracy решает, засчитать ли платёж; то, что в допуск не попало, обрабатывает autorefund.

---

​

Допуск (accuracy)

Если включить допуск, счёт, отклонившийся от суммы (недоплата или переплата) не более чем на N %, всё равно станет paid.

Python

# Разрешить недоплату до 2%
call("/v1/payment/accuracy/set", {"enabled": True, "accuracy_percent": 2})

// Разрешить недоплату до 2%
await call("/v1/payment/accuracy/set", { enabled: true, accuracy_percent: 2 });

• Диапазон accuracy_percent — 1–5, кэп 5 %.
• По умолчанию допуск ~1 %, а не выключен. Если вы ничего не настраивали, счёт с недоплатой/переплатой в пределах ~1 % засчитается как paid. Чтобы требовать ровную сумму (нулевой допуск), нужно явно сохранить настройку выключенной: call("/v1/payment/accuracy/set", {"enabled": False}).
• Для конкретного счёта можно перекрыть настройку полем accuracy_payment_percent в POST /v1/payment.

Пример: выставили 10 USDT, допуск 2 %. Пришло 9.85 USDT — это в пределах 2 %, счёт станет paid. Пришло 9.50 USDT — вне допуска: счёт не закрывается сразу, а ждёт (wrong_amount_waiting) на случай доплаты, и лишь по истечении срока становится wrong_amount (недоплата).

---

​

Автовозврат (autorefund)

Что делать с расхождением, которое не попало в допуск:

Python

# Возвращать и переплату, и истёкшую недоплату
call("/v1/payment/autorefund/set", {"overpay": True, "underpay": True})

// Возвращать и переплату, и истёкшую недоплату
await call("/v1/payment/autorefund/set", { overpay: true, underpay: true });

• overpay: true — при переплате (paid_over) вернуть излишек.
• underpay: true — при истёкшей недоплате (wrong_amount) вернуть полученное.
• Оба флага по умолчанию включены.

Возврат идёт на адрес плательщика. По умолчанию из возвращаемой суммы удерживаются и наша комиссия, и сетевой газ (авто-возвраты по умолчанию «за счёт клиента»): плательщик получает сумма − наша комиссия − газ. Кто платит комиссию возврата — можно переключить на уровне проекта (refund-fee-config). Поддержаны EVM, Tron, TON, Solana. Для Bitcoin/UTXO возврат ручной — через POST /v1/payment/refund.

---

​

Как статусы связаны с настройками

Пришло	Статус	Если accuracy покрывает	Что делает autorefund
Ровно или чуть больше в пределах допуска	paid	—	ничего
Меньше, но в пределах допуска	paid	засчитано как оплата	ничего
Меньше, срок вышел, вне допуска	wrong_amount	—	вернёт при underpay: true
Больше сверх допуска	paid_over	—	вернёт излишек при overpay: true

---

​

Ручное решение по недоплате: /v1/payment/resolve

Автовозврат — политика «по умолчанию». Для конкретного недоплаченного счёта (wrong_amount) решение можно принять вручную — методом POST /v1/payment/resolve:

• action: "accept" — принять частичную оплату: средства остаются у вас, автовозврат для этого счёта отключается. Удобно, когда недоплата копеечная или вы договорились с покупателем.
• action: "refund" — вернуть недоплату плательщику прямо сейчас, не дожидаясь поллера (или когда автовозврат выключен).

Python

call("/v1/payment/resolve", {"order_id": "ord-1001", "action": "accept"})

await call("/v1/payment/resolve", { order_id: "ord-1001", action: "accept" });

Решение одно на счёт: повторный accept — no-op, противоположное действие вернёт resolution.already_resolved. Если покупатель успел доплатить и счёт стал paid, придёт resolution.not_underpaid — сверьтесь с /v1/payment/info.

---

​

Рекомендации

• Включите небольшой допуск (1–2 %) — это резко снижает число «недоплат» из‑за комиссий и округления, при которых покупатель по факту заплатил почти всё.
• Держите автовозврат включённым, чтобы не разбирать расхождения вручную. Помните про ручной возврат для Bitcoin/UTXO.
• Разрешайте доплату (is_payment_multiple: true при создании счёта), если хотите принимать недоплату частями до истечения срока.

---

​

Связанные страницы

Допуск недоплаты

Автовозврат

POST /v1/payment/refund

Возвраты платежей

Объект платежа — статусы