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

Возврат отправляет средства оплаченного платежа обратно покупателю. Технически это операция на движке выплат — списание с вашего баланса. Возврат бывает полный и частичный.

Справочник метода — POST /v1/payment/refund.

---

​

Главное: адрес указывать НЕ обязательно

Самое частое заблуждение — что для возврата нужно где‑то раздобыть адрес покупателя и передать его в запросе. Не нужно. Шлюз запоминает payer_address — адрес, с которого реально пришли деньги, — и по умолчанию возвращает средства именно туда.

Поэтому минимальный полный возврат выглядит так:

Python

call("/v1/payment/refund", {"order_id": "order-1"})   # и всё

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

call("/v1/payment/refund", {
    "order_id": "order-1",       # или uuid платежа
})

await call("/v1/payment/refund", {
  order_id: "order-1",           // или uuid платежа
});

Для Bitcoin/UTXO — с адресом:

Python

call("/v1/payment/refund", {
    "order_id": "order-btc-1",
    "address": "bc1q...",        # для UTXO-сетей обязателен
})

await call("/v1/payment/refund", {
  order_id: "order-btc-1",
  address: "bc1q...",            // для UTXO-сетей обязателен
});

---

​

Частичный возврат

Укажите amount — вернётся только эта часть:

Python

call("/v1/payment/refund", {
    "order_id": "order-1",
    "amount": "10",              # частичная сумма
})

await call("/v1/payment/refund", {
  order_id: "order-1",
  amount: "10",                  // частичная сумма
});

Суммарно по платежу нельзя вернуть больше оплаченного. Несколько частичных возвратов складываются.

---

​

В какой валюте вернутся деньги

Возврат деноминирован в той монете, которая фактически пришла. Если покупатель заплатил 100 USDT — вернутся USDT, а не «эквивалент по текущему курсу».

Курс заново не пересчитывается. Это важно понимать: если цена была в фиате ("currency": "USD"), а за время до возврата курс монеты изменился, то в долларах покупатель получит не ровно то, что заплатил. Шлюз возвращает монету, а не фиатную стоимость — фиат он вообще не хранит. → Модель баланса

---

​

Кто платит и что подтверждается

• Адрес плательщика vs произвольный. По умолчанию возврат уходит на записанный адрес плательщика (payer_address). Возврат, инициированный по API‑ключу, авто‑одобряется и уходит сразу на любой адрес — ключ несёт ту же полноту полномочий, что и при обычной выплате; отдельного подтверждения (POST /v1/payout/approve) не требуется. Поэтому перепроверяйте address, если передаёте его явно: остановить отправленный возврат нельзя.
• Наша комиссия при возврате. Кто её несёт — клиент (получает net) или мерчант (клиент получает gross) — задаётся настройкой refund-fee-config. Шлюз свою комиссию при возврате не покрывает.

Возврат списывает с вашего баланса ВСЮ сумму, которую заплатил покупатель. Не «вашу часть после комиссий» — всю. Это критично, если у вас настроены сплит‑платежи: именно поэтому расчёт по сплитам откладывается на окно удержания.

---

​

Отслеживание возврата

Есть два способа, и первый удобнее.

​

По самому платежу (рекомендуется)

POST /v1/payment/info возвращает состояние возвратов прямо в объекте платежа:

Python

p = call("/v1/payment/info", {"order_id": "order-1"})["result"]

print(p["refund_status"])   # none | partial | full
for r in p["refunds"]:      # список всех возвратов по этому платежу
    print(r)

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 или по вебхукам — это уровень «дошла ли транзакция в блокчейне».

---

​

Автоматический возврат vs ручной

Не путайте два механизма:

	Ручной возврат	Автовозврат
Метод	/v1/payment/refund	/v1/payment/autorefund
Когда	Вы решаете вернуть оплаченный платёж.	Автоматически при недоплате/переплате вне допуска.
Инициатор	Ваш код.	Шлюз.

Про автоматический сценарий — Недоплата, переплата и автовозврат.

---

​

Идемпотентность

Возврат идемпотентен по тройке (платёж, адрес, сумма). Повтор с той же тройкой вернёт уже созданную операцию, а не отправит средства дважды. Дополнительно отправляйте HTTP‑заголовок Idempotency-Key — он защитит от дубля при ретрае после таймаута. → Устойчивый клиент

Массовые возвраты (до 5000 за раз) — POST /v1/refund/batch, см. Массовые операции.

---

​

Ошибки

Код	Значение	Что делать
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/payment/refund

Объект платежа

Кто платит комиссию возврата

Массовые операции

POST /v1/refund/batch, до 5000 возвратов.

Сплит‑платежи

почему возврат влияет на расчёты с партнёрами.

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

Первая выплата