> ## 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. # Публичный статус платежа (страница оплаты) > Без секрета — можно опрашивать прямо из браузера. Содержит `amount_remaining` для подсказки «доплатите X». ## OpenAPI ````yaml /api-reference/openapi.json get /v1/pay/{id} 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/pay/{id}: get: tags: - Оформление (без ключа) summary: Публичный статус платежа (страница оплаты) description: >- Без секрета — можно опрашивать прямо из браузера. Содержит `amount_remaining` для подсказки «доплатите X». responses: '200': content: application/json: schema: properties: result: properties: additional_data: description: >- Ваши приватные данные, которые вернутся в ответе и в вебхуке. type: string address: description: >- Адрес, на который клиент отправляет деньги. На XRP это классический r-адрес ОБЩЕГО кошелька — платёж обязан нести destination_tag, иначе сеть его отклонит. type: string address_muxed: description: >- Только XLM: те же реквизиты одной строкой — muxed-адрес M… (SEP-23), адрес и memo вместе; его же кодирует QR. Пусто на остальных сетях. type: string address_qr_code: description: >- QR-код адреса как PNG data:-URI — можно сразу в . На XRP кодирует X-address (адрес+тег одной строкой). type: string address_xaddress: description: >- Только XRP: те же реквизиты одной строкой в формате X-address (XLS-5) — адрес и тег вместе; его же кодирует QR. Пусто на остальных сетях. type: string amount: description: Сумма к оплате в валюте цены (например, в USD). example: '10.00' type: string amount_paid: description: >- То же, что payment_amount, но всегда строкой (0, если ничего не пришло). type: string amount_remaining: description: >- Сколько ещё осталось доплатить (к оплате − оплачено); 0, если хватает. type: string confirmations: description: Текущее число подтверждений входящего платежа. type: integer created_at: description: Время создания (ISO 8601). example: '2026-07-10T12:00:00Z' type: string currency: description: >- Валюта цены: фиат (USD, EUR, RUB, JPY… — см. pricing_currencies) или монета. Говорит, сколько счёт СТОИТ, а не чем за него платят (это payer_currency). example: USD type: string destination_tag: description: >- Только XRP: числовой destination tag, который клиент ОБЯЗАН указать в переводе (поле «тег/memo получателя» на бирже или в кошельке). Пусто на остальных сетях. type: string expired_at: description: Когда истекает счёт, Unix-время в секундах. example: 1783728000 type: integer is_final: description: true — статус финальный, больше не изменится. type: boolean is_multi: description: >- true — это валюто-агностичная ссылка, клиент ещё не выбрал валюту/сеть. type: boolean memo: description: >- Только XLM (Stellar): числовой memo (тип ID), который клиент ОБЯЗАН указать в переводе — поле «memo» на бирже или в кошельке. Пусто на остальных сетях. type: string network: description: Сеть блокчейна (например, tron). example: tron type: string order_id: description: Ваш номер заказа, который вы передали при создании. type: string payer_address: description: >- Адрес, С КОТОРОГО пришёл первый подтверждённый депозит — на аккаунт-сетях (EVM/Tron/Solana/TON); пусто на UTXO. ⚠ Это НЕ обязательно адрес для возврата: отправителем может быть биржа, сдача UTXO-транзакции или горячий омнибус крипто-он-рампа, если покупатель платил картой. Прежде чем возвращать деньги сюда, смотрите payer_address_is_refundable. type: string payer_address_is_refundable: description: >- true — payer_address принадлежит плательщику, и в /v1/payment/refund можно опустить address (вернём на него). false — адрес возврата неизвестен (UTXO/XRP, оплата картой через он-рамп, адрес не записан): спросите адрес у покупателя и передайте address явно, иначе запрос будет отклонён с refund.no_address. type: boolean payer_amount: description: Сколько нужно отправить в крипте оплаты. example: '10.150000' type: string payer_currency: description: >- Валюта, в которой платит клиент (например, USDT). Пусто у валюто-агностичного счёта (is_multi), пока клиент не выбрал монету — валюты расчёта у него ещё нет. example: USDT type: string payer_email: description: E-mail плательщика, если вы его передали. type: string payment_amount: description: >- Сколько уже подтверждённо оплачено (в крипте оплаты); null, пока не пришло ничего. type: string payment_status: description: >- Статус: select (клиент выбирает валюту) | check (ждём оплату) | confirm_check (ждём подтверждений) | wrong_amount_waiting | paid | paid_over | wrong_amount | cancel | expired. example: check type: string rate_expires_at: description: >- Когда обновится курс, Unix-секунды (курс держится ~5 мин). example: 1783724700 type: integer required_confirmations: description: >- Сколько подтверждений нужно для зачисления (зависит от суммы и сети). example: 20 type: integer txid: description: Хеш входящей транзакции (когда замечена). type: string updated_at: description: Время последнего изменения (ISO 8601). example: '2026-07-10T12:00:00Z' type: string url: description: Ссылка на готовую страницу оплаты. type: string url_return: description: Ссылка «вернуться в магазин» до оплаты. type: string url_success: description: Куда перенаправить после успешной оплаты. type: string uuid: description: >- Наш идентификатор платежа (используйте его в info/refund). type: string type: object state: example: 0 type: integer type: object description: Success security: [] 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 ````