> ## 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. # Список принимаемых валют ## OpenAPI ````yaml /api-reference/openapi.json post /v1/payment/accepted/list 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/accepted/list: post: tags: - Настройки summary: Список принимаемых валют responses: '200': 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 ````