POST /v1/payment/refund

Вернуть средства платежа на адрес. Использует движок выплат (списание с баланса).

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

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

---

​

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

uuid · string

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

order_id · string

Ваша ссылка на заказ платежа.

address · string

Адрес назначения возврата. По умолчанию — payer_address, адрес, с которого пришли деньги.

network · string

Сеть.

amount · string

Частичная сумма. По умолчанию — вся полученная.

Минимально необходимое: uuid или order_id. Всё остальное — по мере надобности.

address необязателен. Не передавайте его — и возврат уйдёт на payer_address платежа. Обязателен он только для Bitcoin/UTXO: у таких платежей нет единого отправителя, payer_address пуст, и без явного адреса вы получите 400 refund.no_address.

​

Заголовки

Idempotency-Key

Любое уникальное значение (≤255 символов), одинаковое во всех повторах одного возврата. Повтор вернёт тот же ответ и заголовок Idempotent-Replayed: true. → Идемпотентность

---

​

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

Обычный случай — вернуть всё плательщику. Ни адреса, ни суммы указывать не надо:

cURL

BODY='{"order_id":"order-1"}'
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" 'POST' '/v1/payment/refund' "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -s https://api.oblodai.com/v1/payment/refund \
  -X POST -H 'Content-Type: application/json' \
  -H "X-Public-Id: $PUBLIC_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Idempotency-Key: refund-order-1" \
  -d "$BODY"

# Вернуть всё, что заплатили, на адрес плательщика:
call("/v1/payment/refund", {"order_id": "order-1"})

# Частичный возврат — тоже на адрес плательщика:
call("/v1/payment/refund", {"order_id": "order-1", "amount": "10"})

# На явный адрес — нужно для Bitcoin/UTXO, либо когда возврат идёт не отправителю:
call("/v1/payment/refund", {"order_id": "order-1", "address": "TZZ...", "network": "tron"})

await call("/v1/payment/refund", { order_id: "order-1" });
await call("/v1/payment/refund", { order_id: "order-1", amount: "10" });
await call("/v1/payment/refund", { order_id: "order-1", address: "TZZ...", network: "tron" });

---

​

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

{
  "state": 0,
  "result": {
    "uuid": "f9e8...01",
    "payment_uuid": "a1b2...c3",
    "order_id": "order-1",
    "amount": "10",
    "currency": "USDT",
    "address": "TZZ...",
    "status": "process",
    "is_final": false
  }
}

---

​

Коды ошибок

Код	Значение
400 refund.no_address	Адрес не передан и не известен адрес плательщика (Bitcoin/UTXO). Передайте address явно.
400 refund.bad_amount	Некорректная сумма.
400 refund.nothing_to_refund	Нечего возвращать. В том числе — если это валюто‑агностичный счёт (is_multi: true), где покупатель ещё не выбрал монету: валюты расчёта нет, значит платежа не было.
400 refund.dust	Сумма возврата ниже пыле‑порога сети.
400 refund.destination_internal	Адрес назначения принадлежит шлюзу.
400 refund.exceeds_refundable	Больше оплаченной суммы вернуть нельзя.
400 refund.exceeds_excess	Возврат переплаты превышает саму переплату.
409 refund.reference_collision	Тот же (платёж, адрес, сумма) уже в работе (идемпотентность).
400 payment.bad_uuid	Некорректный uuid.
400 payment.no_lookup	Не передан ни uuid, ни order_id.
404 payment.not_found	Платёж не найден.

---

​

Нюансы

• Адрес по умолчанию — адрес плательщика. Шлюз запоминает, откуда пришли деньги (payer_address), и без явного address возвращает туда же. На аккаунтных сетях (EVM, Tron, Solana, TON) отправитель известен всегда. На Bitcoin/UTXO единого отправителя нет — там address обязателен.
• Возврат по API‑ключу авто‑одобряется и уходит сразу — как на адрес плательщика, так и на любой другой (отдельное подтверждение через /v1/payout/approve не требуется, как и для обычной выплаты). Поэтому не передавайте address без нужды и перепроверяйте его, если передаёте: отправленный возврат не остановить.
• Валюта возврата — та, что фактически пришла. Возврат деноминирован в монете платежа и не пересчитывается по новому курсу. Если счёт был в USD, а заплатили USDT, вернётся USDT — ровно столько, сколько пришло. Курсовую разницу шлюз не компенсирует.
• Идемпотентность. Заголовок Idempotency-Key либо тройка (платёж, адрес, сумма). Суммарно нельзя вернуть больше оплаченного.
• Кто несёт нашу комиссию при возврате — настраивается через refund-fee-config.
• Автоматический (не ручной) возврат недоплаты/переплаты настраивается отдельно — autorefund.
• Много возвратов сразу — POST /v1/refund/batch (до 5000 за один запрос).
• Что уже возвращено по счёту, видно в полях refunds[] и refund_status ответа POST /v1/payment/info.

---

​

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

POST /v1/payment/autorefund/get · /set

POST /v1/refund/batch

массовые возвраты.

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

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

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

payer_address, refunds[], refund_status.