> ## 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_mode`: `fixed` (сумма задана в `amount_fixed`), `open` (клиент вводит любую сумму, опц. `amount_min`), `range` (клиент вводит в диапазоне `amount_min`…`amount_max`). `currency` — валюта цены (крипто-тикер, напр. `USDT`). Валюту/сеть оплаты можно **закрепить** (`pinned_currency` + `pinned_network`) или оставить пустыми — тогда клиент выбирает их на странице оплаты. `expires_in` — срок жизни ссылки в секундах (0 = **бессрочно**; сами инвойсы при этом живут обычный короткий срок). В ответе — `link_id` и `url` для клиента. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/payment/link 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/link: post: tags: - Платёжные ссылки summary: Создать платёжную ссылку description: >- Переиспользуемая ссылка (как страница доната): по ней платят много людей, каждый платёж — свой инвойс со своим адресом. `amount_mode`: `fixed` (сумма задана в `amount_fixed`), `open` (клиент вводит любую сумму, опц. `amount_min`), `range` (клиент вводит в диапазоне `amount_min`…`amount_max`). `currency` — валюта цены (крипто-тикер, напр. `USDT`). Валюту/сеть оплаты можно **закрепить** (`pinned_currency` + `pinned_network`) или оставить пустыми — тогда клиент выбирает их на странице оплаты. `expires_in` — срок жизни ссылки в секундах (0 = **бессрочно**; сами инвойсы при этом живут обычный короткий срок). В ответе — `link_id` и `url` для клиента. requestBody: content: application/json: schema: properties: amount_fixed: description: Сумма — для режима fixed; обязательна в этом режиме example: '25.00' type: string amount_max: description: Верхняя граница — для range; обязательна в этом режиме example: '1000.00' type: string amount_min: description: >- Нижняя граница: необязательный «пол» для open, обязательный минимум для range example: '1.00' type: string amount_mode: description: 'Режим суммы: fixed | open | range' example: open type: string currency: description: >- Валюта цены — фиат (USD, EUR, RUB, …) или монета; список — pricing_currencies из GET /v1/currencies example: USD type: string description: description: Описание на странице оплаты type: string expires_in: description: >- Срок жизни ссылки, секунд от момента создания; 0 (по умолчанию) — ссылка бессрочная type: integer pinned_currency: description: >- Валюта расчёта (монета), закреплённая за ссылкой; пусто — монету выбирает покупатель example: USDT type: string pinned_network: description: >- Сеть расчёта, закреплённая за ссылкой; пусто — сеть выбирает покупатель example: tron type: string title: description: Заголовок на странице оплаты example: Поддержать проект type: string required: - amount_mode - currency type: object required: true responses: '200': content: application/json: schema: properties: result: properties: link_id: description: Идентификатор ссылки example: 5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40 type: string url: description: >- Публичный URL страницы оплаты — его вы даёте покупателю: кнопкой, в письме, QR-кодом example: >- https://pay.oblodai.com/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40 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 ````