POST /v1/payment/resolve

Решите судьбу недоплаченного счёта: принять частичную оплату или вернуть её плательщику.

Решение судьбы недоплаченного платежа (статус wrong_amount): accept — оставить частичную оплату себе (и отключить автовозврат для этого счёта) или refund — вернуть средства плательщику. Средства недоплаты к этому моменту уже зачислены на ваш баланс, вебхук invoice.wrong_amount уже отправлен.

URL: https://api.oblodai.com/v1/payment/resolve · Аутентификация: обязательна, payout-ключ · Идемпотентность: заголовок Idempotency-Key поддержан; решение дополнительно идемпотентно на уровне счёта (одно на счёт).

Примеры используют хелпер call() и переменные $SECRET/$PUBLIC_ID — их определение см. в Как подписать запрос. Проще не писать подпись руками, а взять SDK.

​

Параметры запроса

uuid · string

UUID платежа. Нужен uuid или order_id.

order_id · string

Ваш идентификатор платежа.

action · string · обязательно

accept — принять частичную оплату · refund — вернуть плательщику.

address · string

Только для refund: адрес возврата. По умолчанию — записанный payer_address платежа; если он пуст (Bitcoin/UTXO), адрес обязателен, иначе refund.no_address.

network · string

Только для refund: сеть возврата, по умолчанию — сеть платежа.

reference · string

Только для refund: ваш ключ дедупликации возврата.

​

Пример запроса

Python

# принять недоплату (оставить частичную оплату себе)
call("/v1/payment/resolve", {"order_id": "ord-1001", "action": "accept"})

# либо вернуть плательщику
call("/v1/payment/resolve", {"order_id": "ord-1001", "action": "refund"})

// принять недоплату (оставить частичную оплату себе)
await call("/v1/payment/resolve", { order_id: "ord-1001", action: "accept" });

// либо вернуть плательщику
await call("/v1/payment/resolve", { order_id: "ord-1001", action: "refund" });

​

Пример ответа

accept

{
  "state": 0,
  "result": {
    "payment_uuid": "e0a1…",
    "order_id": "ord-1001",
    "resolution": "accepted",
    "amount_kept": "48.5",
    "currency": "USDT"
  }
}

{
  "state": 0,
  "result": {
    "payment_uuid": "e0a1…",
    "order_id": "ord-1001",
    "resolution": "refunded",
    "uuid": "f2b3…",
    "amount": "48.5",
    "currency": "USDT",
    "address": "0xPayer…",
    "status": "check",
    "is_final": false
  }
}

При refund ответ содержит обычный объект возврата-выплаты (uuid, status из словаря выплат) — отслеживайте его как выплату.

​

Коды ошибок

resolution.bad_action · 400

action не accept и не refund. Повтор: Нет.

resolution.not_underpaid · 409

Платёж не в статусе wrong_amount (например, поздняя доплата перевела его в paid). Повтор: Нет — сверьтесь с /v1/payment/info.

resolution.already_resolved · 409

Решение по счёту уже принято (противоположное действие). Повтор: Нет.

resolution.already_refunded · 409

По счёту уже был возврат — принять недоплату нельзя. Повтор: Нет.

refund.no_address · 400

Не указан адрес возврата, а payer_address у платежа пуст (UTXO-сети). Повтор: Нет — передайте address.

payment.not_found · 404

Платёж не найден. Повтор: Нет — сверьте uuid/order_id.

resolution.disabled · 503

Функция выключена на шлюзе. Повтор: Нет — обратитесь в поддержку.

Возврат также может вернуть обычные ошибки возвратов: refund.nothing_to_refund, refund.dust, refund.destination_internal, compliance.blocked и др. — см. Возврат платежа.

​

Нюансы

• accept останавливает автовозврат для этого счёта: решение и поллер автовозврата сериализованы на локе счёта — гонки «приняли и одновременно вернули» нет.
• Повторный accept — no-op (идемпотентно); refund после accept (и наоборот) → resolution.already_resolved.
• accept не эмитит вебхуков; refund порождает выплату с обычными payout.* событиями.

​

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

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

Автовозврат: настройки

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

Объект Payment