Платёжные ссылки

Платёжная ссылка — это постоянный URL, по которому кто угодно может вам заплатить. Вы создаёте её один раз, дальше она работает сама: покупатель открывает ссылку, при необходимости вводит сумму, выбирает монету и сеть, платит — и на вашем балансе появляются деньги.

Это единственный способ принимать платежи БЕЗ своего бэкенда. Обычная интеграция требует сервера: каждый вызов API подписывается секретом, а секрет нельзя отдавать в браузер. У платёжной ссылки этой проблемы нет — страница оплаты живёт на стороне Oblodai и работает по публичным эндпоинтам, без вашего ключа. Поэтому ссылку можно повесить на кнопку в Tilda/Wix, отправить в мессенджере или положить в шапку профиля.

Справочник методов — POST /v1/payment/link и публичные методы страницы оплаты.

---

​

Когда это ваш инструмент

• Сайт на конструкторе (Tilda, Wix, Webflow) — сервера нет, писать код негде.
• Донаты и чаевые — сумму называет плательщик, а не вы.
• Продажи в мессенджере/соцсетях — сайта вообще нет, есть только диалог.
• Разовый счёт клиенту — выставить и отправить, не заводя интеграцию.

Если у вас есть бэкенд и вы хотите автоматически выдавать товар по факту оплаты — вам, скорее всего, нужен обычный счёт: Приём первого платежа. Ссылка и счёт не исключают друг друга: ссылка при оплате создаёт настоящий платёж, с теми же статусами и теми же вебхуками.

---

​

Шаг 1. Создать ссылку

Python

link = call("/v1/payment/link", {
    "title": "Подписка Pro",
    "description": "Доступ на 30 дней",
    "amount_mode": "fixed",
    "currency": "USD",            # валюта ЦЕНЫ
    "amount_fixed": "10.00",
    "expires_in": 0,              # 0 = бессрочная
})["result"]

print(link["link_id"])            # для управления ссылкой
print(link["url"])                # ЭТО и даёте покупателю

const link = (await call("/v1/payment/link", {
  title: "Подписка Pro",
  description: "Доступ на 30 дней",
  amount_mode: "fixed",
  currency: "USD",            // валюта ЦЕНЫ
  amount_fixed: "10.00",
  expires_in: 0,              // 0 = бессрочная
})).result;

console.log(link.link_id);    // для управления ссылкой
console.log(link.url);        // ЭТО и даёте покупателю

Всё. url можно вешать на кнопку, отправлять в чат, печатать в QR‑коде.

---

​

Шаг 2. Выбрать режим суммы

Главное решение при создании — кто называет сумму. Режимов три.

amount_mode	Кто определяет сумму	Обязательные поля	Типичный сценарий
fixed	Вы, заранее	amount_fixed	Товар, подписка
open	Покупатель	— (amount_min опционален)	Донаты, чаевые
range	Покупатель, в ваших рамках	amount_min + amount_max	Пополнение, предоплата

​

fixed — сумма зафиксирована

Python

call("/v1/payment/link", {
    "title": "Курс по Python",
    "amount_mode": "fixed",
    "currency": "USD",
    "amount_fixed": "49.00",
    "expires_in": 0,
})

await call("/v1/payment/link", {
  title: "Курс по Python",
  amount_mode: "fixed",
  currency: "USD",
  amount_fixed: "49.00",
  expires_in: 0,
});

Покупатель сумму не вводит и не меняет — он видит 49 USD и платит их.

​

open — сумму вводит покупатель (донаты)

Python

call("/v1/payment/link", {
    "title": "Поддержать проект",
    "amount_mode": "open",
    "currency": "USD",
    "amount_min": "1.00",     # необязательный ПОЛ: меньше $1 не примем
    "expires_in": 0,
})

await call("/v1/payment/link", {
  title: "Поддержать проект",
  amount_mode: "open",
  currency: "USD",
  amount_min: "1.00",     // необязательный ПОЛ: меньше $1 не примем
  expires_in: 0,
});

Поле ввода суммы на странице оплаты пустое — сколько напишет плательщик, столько и заплатит. Верхней границы нет. amount_min — не обязателен, но полезен: он отсекает копеечные платежи, которые целиком съест комиссия сети.

​

range — сумма в диапазоне

Python

call("/v1/payment/link", {
    "title": "Пополнение баланса",
    "amount_mode": "range",
    "currency": "USD",
    "amount_min": "5.00",
    "amount_max": "1000.00",
    "expires_in": 0,
})

await call("/v1/payment/link", {
  title: "Пополнение баланса",
  amount_mode: "range",
  currency: "USD",
  amount_min: "5.00",
  amount_max: "1000.00",
  expires_in: 0,
});

Покупатель вводит сумму, но шлюз проверит её по границам: меньше amount_min → paylink.below_min, больше amount_max → paylink.above_max.

​

Валюта цены: не только доллары

currency — это валюта ЦЕНЫ, и она не обязана быть USD. Работает любой из 23 поддерживаемых фиатов (EUR, GBP, RUB, UAH, PLN, CZK, TRY…) или монета (USDT, BTC). Не путайте с валютой расчёта — тем, чем реально платят.

Python

# Донат «от €5», бессрочный
call("/v1/payment/link", {"title": "Поддержать проект", "amount_mode": "open",
                          "currency": "EUR", "amount_min": "5", "expires_in": 0})

# Фиксированные 5000 ₽
call("/v1/payment/link", {"title": "Консультация", "amount_mode": "fixed",
                          "currency": "RUB", "amount_fixed": "5000", "expires_in": 0})

// Донат «от €5», бессрочный
await call("/v1/payment/link", { title: "Поддержать проект", amount_mode: "open",
                                 currency: "EUR", amount_min: "5", expires_in: 0 });

// Фиксированные 5000 ₽
await call("/v1/payment/link", { title: "Консультация", amount_mode: "fixed",
                                 currency: "RUB", amount_fixed: "5000", expires_in: 0 });

Тенге, сом и сум не поддерживаются — попытка вернёт 400 paylink.unknown_currency. Полный список и причина — Три режима создания счёта.

Знаки после запятой у суммы, которую вводит покупатель, проверяются по валюте ЦЕНЫ. В open/range‑ссылке с ценой в евро «5.99» пройдёт, а в ссылке с ценой в иене «500.50» будет отвергнуто: у JPY (и KRW) нет дробной части. Если вы рисуете свою форму ввода — не давайте вводить копейки там, где валюта их не имеет.

---

​

Шаг 3. Решить, кто выбирает монету и сеть

Второе решение: закреплять ли валюту расчёта.

Python

# Вариант А. Покупатель выбирает сам (pinned_* не заданы)
call("/v1/payment/link", {
    "title": "Донат", "amount_mode": "open", "currency": "USD", "expires_in": 0,
})
# → на странице оплаты покупатель сам выбирает: USDT/tron, BTC/bitcoin, TRX/tron…

# Вариант Б. Вы закрепили монету и сеть
call("/v1/payment/link", {
    "title": "Подписка Pro", "amount_mode": "fixed",
    "currency": "USD", "amount_fixed": "10.00",
    "pinned_currency": "USDT",     # валюта расчёта
    "pinned_network": "tron",      # сеть
    "expires_in": 0,
})
# → выбора нет: платят USDT в сети Tron

// Вариант А. Покупатель выбирает сам (pinned_* не заданы)
await call("/v1/payment/link", {
  title: "Донат", amount_mode: "open", currency: "USD", expires_in: 0,
});
// → на странице оплаты покупатель сам выбирает: USDT/tron, BTC/bitcoin, TRX/tron…

// Вариант Б. Вы закрепили монету и сеть
await call("/v1/payment/link", {
  title: "Подписка Pro", amount_mode: "fixed",
  currency: "USD", amount_fixed: "10.00",
  pinned_currency: "USDT",     // валюта расчёта
  pinned_network: "tron",      // сеть
  expires_in: 0,
});
// → выбора нет: платят USDT в сети Tron

Не закрепляйте без нужды — чем шире выбор, тем выше конверсия. Закрепление имеет смысл, если вы сознательно принимаете только один актив (например, только USDT в дешёвой сети, чтобы не разбирать зоопарк монет на балансе).

---

​

Шаг 4. Срок жизни

Python

"expires_in": 0        # БЕССРОЧНАЯ — работает, пока вы её не выключите
"expires_in": 86400    # живёт сутки с момента создания (секунды)

expires_in: 0        // БЕССРОЧНАЯ — работает, пока вы её не выключите
expires_in: 86400    // живёт сутки с момента создания (секунды)

• Бессрочная (0) — для донатов, кнопки «Оплатить» на сайте, ссылки в профиле. Такая ссылка принимает платежи многократно, от разных людей.
• С TTL — для разового счёта конкретному клиенту: выставили, дали срок, дальше ссылка протухает.

---

​

Что происходит, когда покупатель платит

Страница оплаты работает по публичным эндпоинтам — без вашего API‑ключа:

1. Покупатель открывает url
        ↓  страница читает GET /v1/link/{id} — заголовок, описание, режим суммы
2. Вводит сумму (если режим open/range) и выбирает монету (если не закреплена)
        ↓
3. POST /v1/link/{id}/checkout → создаётся НАСТОЯЩИЙ платёж, возвращается его uuid
        ↓
4. Дальше всё как у обычного счёта: адрес, QR, подтверждения сети, статусы
        ↓
5. Оплачено → на балансе деньги; если у вас есть бэкенд — придёт вебхук invoice.paid

Ключевое: /v1/link/{id}/checkout создаёт обычный платёж. Одна ссылка порождает столько платежей, сколько раз по ней заплатили. Никакой отдельной сущности «оплата ссылки» нет — есть привычные платежи, которые вы видите в истории, по которым приходят вебхуки и с которых делаются возвраты.

→ Публичные методы ссылки

---

​

Как узнать, что по ссылке заплатили

Способ зависит от того, есть ли у вас сервер.

Есть бэкенд — ловите вебхук invoice.paid, как для любого платежа. → Настройка вебхуков

Нет бэкенда — смотрите платежи по ссылке в кабинете или запрашивайте их:

Python

info = call("/v1/payment/link/info", {
    "link_id": "lnk_…",
    "limit": 50, "offset": 0,
})["result"]
# в ответе — сама ссылка и список платежей, созданных по ней

const info = (await call("/v1/payment/link/info", {
  link_id: "lnk_…",
  limit: 50, offset: 0,
})).result;
// в ответе — сама ссылка и список платежей, созданных по ней

Хотите чек покупателю на почту — на странице оплаты есть поле email, и checkout принимает payer_email. Чек уйдёт автоматически после оплаты. → Счёт и чек на почту

---

​

Управление ссылками

Python

# Список всех ссылок
call("/v1/payment/link/list", {"limit": 50, "offset": 0})

# Выключить ссылку (перестанет принимать платежи)
call("/v1/payment/link/toggle", {"link_id": "lnk_…", "active": False})

# Включить обратно
call("/v1/payment/link/toggle", {"link_id": "lnk_…", "active": True})

// Список всех ссылок
await call("/v1/payment/link/list", { limit: 50, offset: 0 });

// Выключить ссылку (перестанет принимать платежи)
await call("/v1/payment/link/toggle", { link_id: "lnk_…", active: false });

// Включить обратно
await call("/v1/payment/link/toggle", { link_id: "lnk_…", active: true });

Выключение обратимо и не трогает уже созданные по ссылке платежи — они живут своей жизнью. Это основной способ «закрыть» бессрочную ссылку: удалять её не нужно.

---

​

Ошибки

Ошибки создания (ваш вызов):

Код	Значение
paylink.bad_mode	amount_mode не fixed/open/range.
paylink.bad_amount	Некорректная сумма.
paylink.not_positive	Сумма ≤ 0.
paylink.bad_min / paylink.bad_max	Некорректная нижняя/верхняя граница.
paylink.bad_range	amount_min больше amount_max.
paylink.unknown_currency	Валюта не поддерживается. → GET /v1/currencies
paylink.disabled	Ссылки временно выключены (503) — повторите позже.

Ошибки оплаты (их увидит покупатель на странице):

Код	Значение
paylink.not_found / paylink.bad_id	Ссылки нет, она выключена или истёк её срок (expires_in).
paylink.amount_required	Режим open/range, а сумма не введена.
paylink.below_min	Сумма меньше amount_min.
paylink.above_max	Сумма больше amount_max.

---

​

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

POST /v1/payment/link · /list · /info · /toggle

GET /v1/link/{id} · POST /v1/link/{id}/checkout

публичные методы.

Регистрация и ключи

что делать, если сервера нет.

Счёт и чек на почту

автоматический чек плательщику.

Три режима создания счёта

цена vs валюта расчёта.

Приём первого платежа

обычный счёт, когда бэкенд есть.