> ## Documentation Index > Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Возвраты платежей Возврат отправляет средства оплаченного платежа обратно покупателю. Технически это операция на движке выплат — списание с вашего баланса. Возврат бывает **полный** и **частичный**. Справочник метода — [`POST /v1/payment/refund`](/reference/payment-refund). *** ## Главное: адрес указывать НЕ обязательно Самое частое заблуждение — что для возврата нужно где‑то раздобыть адрес покупателя и передать его в запросе. **Не нужно.** Шлюз запоминает `payer_address` — адрес, с которого реально пришли деньги, — и по умолчанию возвращает средства **именно туда**. Поэтому минимальный полный возврат выглядит так: ```python Python theme={null} call("/v1/payment/refund", {"order_id": "order-1"}) # и всё ``` ```js Node.js theme={null} await call("/v1/payment/refund", { order_id: "order-1" }); // и всё ``` Ни `address`, ни `amount` не нужны: вернётся вся полученная сумма на адрес плательщика. **Не спрашивайте адрес у покупателя без необходимости.** Это лишний шаг, источник опечаток и классический вектор мошенничества («напишите мне другой адрес для возврата»). Возврат на `payer_address` — и проще, и безопаснее. ### Когда `address` всё-таки нужен | Ситуация | `address` | | ----------------------------------------------------------------------- | ---------------------------------------------- | | Обычный возврат покупателю (Tron, Ethereum, BSC, Polygon, Solana, TON…) | **Не нужен** — уйдёт на `payer_address`. | | **Bitcoin и другие UTXO‑сети** | **Обязателен.** Иначе `400 refund.no_address`. | | Возврат на **другой** адрес (не тот, с которого платили) | Нужен — и потребует подтверждения (см. ниже). | **Почему UTXO — исключение.** В сетях вроде Bitcoin у транзакции нет одного однозначного отправителя: она собирается из нескольких входов, которые могут принадлежать разным адресам (в том числе адресам биржи или чужого кошелька). «Адреса плательщика» там попросту не существует как надёжного понятия — поэтому шлюз не угадывает, а требует указать адрес явно. *** ## Полный возврат Не указывайте `amount` — вернётся вся полученная сумма: ```python Python theme={null} call("/v1/payment/refund", { "order_id": "order-1", # или uuid платежа }) ``` ```js Node.js theme={null} await call("/v1/payment/refund", { order_id: "order-1", // или uuid платежа }); ``` Для Bitcoin/UTXO — с адресом: ```python Python theme={null} call("/v1/payment/refund", { "order_id": "order-btc-1", "address": "bc1q...", # для UTXO-сетей обязателен }) ``` ```js Node.js theme={null} await call("/v1/payment/refund", { order_id: "order-btc-1", address: "bc1q...", // для UTXO-сетей обязателен }); ``` *** ## Частичный возврат Укажите `amount` — вернётся только эта часть: ```python Python theme={null} call("/v1/payment/refund", { "order_id": "order-1", "amount": "10", # частичная сумма }) ``` ```js Node.js theme={null} await call("/v1/payment/refund", { order_id: "order-1", amount: "10", // частичная сумма }); ``` Суммарно по платежу **нельзя вернуть больше оплаченного**. Несколько частичных возвратов складываются. *** ## В какой валюте вернутся деньги Возврат деноминирован в **той монете, которая фактически пришла**. Если покупатель заплатил 100 USDT — вернутся USDT, а не «эквивалент по текущему курсу». **Курс заново не пересчитывается.** Это важно понимать: если цена была в фиате (`"currency": "USD"`), а за время до возврата курс монеты изменился, то в долларах покупатель получит не ровно то, что заплатил. Шлюз возвращает монету, а не фиатную стоимость — фиат он вообще не хранит. → [Модель баланса](/guides/balance-and-funds) *** ## Кто платит и что подтверждается * **Адрес плательщика vs произвольный.** По умолчанию возврат уходит на **записанный адрес плательщика** (`payer_address`). Возврат, инициированный по API‑ключу, **авто‑одобряется** и уходит сразу **на любой адрес** — ключ несёт ту же полноту полномочий, что и при обычной выплате; отдельного подтверждения ([`POST /v1/payout/approve`](/reference/payout-approve)) не требуется. Поэтому перепроверяйте `address`, если передаёте его явно: остановить отправленный возврат нельзя. * **Наша комиссия при возврате.** Кто её несёт — клиент (получает net) или мерчант (клиент получает gross) — задаётся настройкой [`refund-fee-config`](/reference/payout-refund-fee-config). Шлюз свою комиссию при возврате не покрывает. **Возврат списывает с вашего баланса ВСЮ сумму, которую заплатил покупатель.** Не «вашу часть после комиссий» — всю. Это критично, если у вас настроены [сплит‑платежи](/guides/split-payments): именно поэтому расчёт по сплитам откладывается на окно удержания. *** ## Отслеживание возврата Есть два способа, и первый удобнее. ### По самому платежу (рекомендуется) [`POST /v1/payment/info`](/reference/payment-info) возвращает состояние возвратов прямо в объекте платежа: ```python Python theme={null} p = call("/v1/payment/info", {"order_id": "order-1"})["result"] print(p["refund_status"]) # none | partial | full for r in p["refunds"]: # список всех возвратов по этому платежу print(r) ``` ```js Node.js theme={null} const p = (await call("/v1/payment/info", { order_id: "order-1" })).result; console.log(p.refund_status); // none | partial | full for (const r of p.refunds) { // список всех возвратов по этому платежу console.log(r); } ``` | `refund_status` | Значение | | --------------- | ----------------------- | | `none` | Возвратов не было. | | `partial` | Возвращена часть суммы. | | `full` | Возвращено полностью. | Это самый простой способ ответить на вопрос «а мы вообще возвращали деньги по этому заказу и сколько?» — не нужно ничего сопоставлять руками. ### По операции возврата Ответ метода возврата содержит `uuid` операции и её `status` (как у выплаты). Следить за движением конкретной операции можно через [`POST /v1/payout/info`](/reference/payout-info) или по вебхукам — это уровень «дошла ли транзакция в блокчейне». *** ## Автоматический возврат vs ручной Не путайте два механизма: | | Ручной возврат | Автовозврат | | --------- | ------------------------------------------------- | --------------------------------------------------------- | | Метод | [`/v1/payment/refund`](/reference/payment-refund) | [`/v1/payment/autorefund`](/reference/payment-autorefund) | | Когда | Вы решаете вернуть оплаченный платёж. | Автоматически при недоплате/переплате вне допуска. | | Инициатор | Ваш код. | Шлюз. | Про автоматический сценарий — [Недоплата, переплата и автовозврат](/guides/under-overpayment). *** ## Идемпотентность Возврат идемпотентен по тройке `(платёж, адрес, сумма)`. Повтор с той же тройкой вернёт уже созданную операцию, а не отправит средства дважды. Дополнительно отправляйте HTTP‑заголовок `Idempotency-Key` — он защитит от дубля при ретрае после таймаута. → [Устойчивый клиент](/guides/resilient-client#главный-принцип) Массовые возвраты (до 5000 за раз) — [`POST /v1/refund/batch`](/reference/refund-batch), см. [Массовые операции](/guides/batch-operations). *** ## Ошибки | Код | Значение | Что делать | | ------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400 refund.no_address` | Адрес назначения не передан **и** не может быть определён автоматически. | Это Bitcoin/UTXO‑сеть: передайте `address` явно. | | `400 refund.bad_amount` | Некорректная сумма. | Проверьте `amount`; больше оплаченного вернуть нельзя. | | `400 refund.nothing_to_refund` | Возвращать нечего. | Причины: платёж **не оплачен**; уже возвращён полностью; **или это валюто‑агностичный счёт, где покупатель ещё не выбрал монету** — валюты расчёта нет, значит и возвращать нечего. | | `404 payment.not_found` | Платёж не найден. | Сверьте `uuid`/`order_id`. | *** ## Связанные страницы `POST /v1/refund/batch`, до 5000 возвратов. почему возврат влияет на расчёты с партнёрами.