> ## Documentation Index > Fetch the complete documentation index at: https://docs.oblodai.com/llms.txt > Use this file to discover all available pages before exploring further. # Вернуть платёж > Возврат — это списание с вашего баланса. `address` (куда вернуть) можно опустить ТОЛЬКО если в платеже `payer_address_is_refundable` = true: тогда вернём на записанный адрес плательщика (`payer_address`). Если там false — адрес плательщика нам известен, но он не является адресом возврата (Bitcoin/UTXO: первый вход мог быть биржей или сдачей; XRP: общий адрес биржи с тегом назначения; оплата КАРТОЙ через крипто-он-рамп: отправитель — омнибусный горячий кошелёк провайдера, а не покупатель). Возврат туда уходит безвозвратно тому, кто денег не платил, поэтому запрос без `address` будет отклонён (`refund.no_address`): спросите адрес у покупателя и передайте его явно. Нужен `uuid`/`order_id` платежа. По умолчанию вернём всю полученную сумму; можно указать частичную `amount`. Идемпотентно по `(платёж, адрес, сумма)`; суммарно нельзя вернуть больше, чем оплачено. Возврат на записанный адрес плательщика подтверждается автоматически — кроме платежей картой через он-рамп, где такой возврат уходит в обычную очередь подтверждения. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/payment/refund openapi: 3.1.0 info: description: >- Публичный HTTP API для приёма криптоплатежей, отправки выплат и возвратов. Совместим с форматом Heleket: каждый запрос подписывается вашим **API-ключом** (`oblodai_…`), а ответ приходит в конверте `{ "state": 0, "result": … }`. ## Быстрый старт (за 3 шага) 1. Получите **API-ключ** в кабинете — **один ключ на всё**: приём платежей, выплаты, возвраты. У него есть публичный id (`oblodai_…`) и секрет (`oblodai_live_…`, показывается один раз). 2. Создайте счёт: `POST /v1/payment` с телом `{"amount":"10","currency":"USD","order_id":"order-1"}`. В ответе будет `url` — отправьте клиента туда, либо покажите `address` + `payer_amount` сами. 3. Когда клиент заплатит, мы пришлём вам **вебхук** и статус станет `paid`. Всё. ## Авторизация (подпись запроса) На каждый защищённый вызов шлите три заголовка: | Заголовок | Значение | |---|---| | `X-Public-Id` | публичный id вашего ключа (`oblodai_…`) | | `X-Timestamp` | текущее время Unix в **секундах** | | `X-Signature` | `hex(HMAC-SHA256(секрет, "\n<МЕТОД>\n<путь>\n<тело>"))` | **Подписываемая строка** — это метка времени, HTTP-метод, путь (с query, если есть) и точное тело запроса, склеенные переводами строк `\n`. Пример на PHP: ```php $ts = time(); $body = json_encode(['amount' => '10', 'currency' => 'USD', 'order_id' => 'order-1']); $sign = hash_hmac('sha256', $ts."\n".'POST'."\n".'/v1/payment'."\n".$body, $secret); // заголовки: X-Public-Id: oblodai_…, X-Timestamp: $ts, X-Signature: $sign ``` Запросы вне окна допустимого расхождения времени отклоняются — держите часы синхронными. **Один ключ на всё:** этот ключ авторизует и приём платежей, и выплаты, и возвраты — берегите его секрет (при утечке его можно перевыпустить в кабинете). ## Формат ответа и ошибок Успех: `{ "state": 0, "result": { … } }`. Ошибка: HTTP-код 4xx/5xx и тело `{ "error": { "code": "...", "message": "..." } }`. Все денежные суммы — строки (чтобы не терять точность). ## Идемпотентность (повторы безопасны) Денежные вызовы идемпотентны по естественному ключу — повтор не сделает двойного действия: платежи и статик-кошельки по `order_id` (кошелёк — по `currency+network+order_id`), выплаты по `order_id`, возвраты по `(платёж, адрес, сумма)` с суммарным лимитом «не больше оплаченного». Входящие депозиты зачисляются ровно один раз, сколько бы раз сеть их ни пере-транслировала (дедуп по `(сеть, txid, output)`). ## Коллбэки (вебхуки) При смене статуса платежа мы делаем `POST` с JSON-телом (форма `Callback`: `type, uuid, order_id, amount, currency, payment_amount, payer_amount, payer_currency, status, is_final, txid, additional_data`) на ваш URL (`url_callback` у платежа/выплаты, либо endpoint проекта из `POST /v1/webhooks`). Доставка **как минимум один раз** с ретраями ~24ч, поэтому **ваш обработчик обязан быть идемпотентным** (дедуп по `uuid`+`status`). Проверяйте подпись `X-Webhook-Signature: hex(HMAC-SHA256(секрет, "." + сырое_тело))`. ## Недо- и переплата, автовозвраты Магазин задаёт допуск сумм (`/v1/payment/accuracy/set`, 1–5% или выключено). В пределах допуска платёж — `paid`. Вне: **переплата** (`paid_over`) авто-возвращает излишек, а истёкшая **недоплата** (`wrong_amount`) авто-возвращает средства — оба за вычетом газа (и комиссии по умолчанию), на адрес плательщика (EVM/Tron/TON/Solana; Bitcoin/UTXO — вручную). Переключается на магазин через `/v1/payment/autorefund/set` (оба по умолчанию ВКЛ). ## Статусы платежа `check` (ждём оплату) · `confirm_check` (видим tx, ждём подтверждений) · `wrong_amount_waiting` (недоплата, ждём остаток) · `paid` (оплачено) · `paid_over` (переплата) · `wrong_amount` (недоплата, срок вышел) · `cancel` / `expired` (отменён/просрочен). title: API мерчанта oblodai version: 1.0.0 servers: - description: Продакшн url: https://api.oblodai.com security: - PublicId: [] Signature: [] Timestamp: [] tags: - description: 'Приём оплаты: создать счёт, узнать статус, история, QR.' name: Платежи - description: 'Многоразовые ссылки на оплату: одна ссылка — много платежей.' name: Платёжные ссылки - description: Вернуть деньги плательщику (списание с вашего баланса). name: Возвраты - description: Отправить деньги на адрес (списание с вашего баланса). name: Выплаты - description: 'Выплата без адреса: получатель сам вводит адрес по секретной ссылке.' name: Выплатные ссылки - description: 'Асинхронные батчи: платежи, возвраты, выплаты, переводы пачками.' name: Массовые операции - description: Автоматическое разделение поступлений между получателями. name: Сплит-платежи - description: Постоянные (статические) адреса пополнения под клиента. name: Кошельки - description: Балансы мерчанта и курсы обмена. name: Баланс и курсы - description: Регистрация endpoint'а для коллбэков, тест и переотправка. name: Вебхуки - description: 'Настройки магазина: допуск сумм, скидки, автовозвраты, валюты, авто-вывод.' name: Настройки - description: Ротация ключей и IP-allowlist API. name: Ключи и безопасность - description: Реферальная программа. name: Рефералы - description: Эндпоинты для страницы оплаты — работают без секрета. name: Оформление (без ключа) - description: 'Dev-store: тестовые деньги, симуляция депозитов и повтор вебхуков.' name: Песочница paths: /v1/payment/refund: post: tags: - Возвраты summary: Вернуть платёж description: >- Возврат — это списание с вашего баланса. `address` (куда вернуть) можно опустить ТОЛЬКО если в платеже `payer_address_is_refundable` = true: тогда вернём на записанный адрес плательщика (`payer_address`). Если там false — адрес плательщика нам известен, но он не является адресом возврата (Bitcoin/UTXO: первый вход мог быть биржей или сдачей; XRP: общий адрес биржи с тегом назначения; оплата КАРТОЙ через крипто-он-рамп: отправитель — омнибусный горячий кошелёк провайдера, а не покупатель). Возврат туда уходит безвозвратно тому, кто денег не платил, поэтому запрос без `address` будет отклонён (`refund.no_address`): спросите адрес у покупателя и передайте его явно. Нужен `uuid`/`order_id` платежа. По умолчанию вернём всю полученную сумму; можно указать частичную `amount`. Идемпотентно по `(платёж, адрес, сумма)`; суммарно нельзя вернуть больше, чем оплачено. Возврат на записанный адрес плательщика подтверждается автоматически — кроме платежей картой через он-рамп, где такой возврат уходит в обычную очередь подтверждения. requestBody: content: application/json: schema: properties: address: description: >- Адрес назначения возврата. По умолчанию — payer_address платежа; обязателен только для Bitcoin/UTXO. type: string amount: description: Частичная сумма. По умолчанию — вся полученная. example: '10' type: string network: description: Сеть. example: tron type: string order_id: description: Ваша ссылка на заказ платежа. Нужен uuid или order_id. example: order-1 type: string reference: description: >- Необязательный ключ идемпотентности возврата: различает два разных возврата с одинаковыми (платёж, адрес, сумма); повтор с тем же значением дедуплицируется. Это не order_id. type: string uuid: description: Идентификатор платежа. Нужен uuid или order_id. type: string type: object required: true responses: '200': content: application/json: schema: properties: result: properties: address: description: Адрес, куда вернули деньги. type: string amount: description: Сумма возврата в монете платежа. example: '10' type: string currency: description: Валюта возврата (монета платежа). example: USDT type: string is_final: description: true — возврат в терминальном статусе. type: boolean order_id: description: order_id платежа, по которому сделан возврат. type: string payment_uuid: description: Идентификатор платежа, который возвращаем. type: string status: description: >- Укрупнённый статус выплаты-возврата: check | process | paid | fail | cancel. example: process type: string uuid: description: Идентификатор возврата (это выплата). type: string type: object state: example: 0 type: integer type: object description: Success components: securitySchemes: PublicId: description: '`pk_live_…` для платёжных эндпоинтов, `wk_live_…` для выплат/возвратов.' in: header name: X-Public-Id type: apiKey Signature: description: hex(HMAC-SHA256(секрет, "\n<МЕТОД>\n<путь>\n<тело>")) in: header name: X-Signature type: apiKey Timestamp: description: Текущее время Unix в секундах (в пределах допустимого расхождения). in: header name: X-Timestamp type: apiKey ````