Публичная страница ссылки

Методы: GET /v1/link/{id} · POST /v1/link/{id}/checkout

Публичные методы платёжной ссылки: показать ссылку покупателю и создать по ней счёт.

Публичные методы. Аутентификация не требуется — их вызывает браузер покупателя, у которого нет и не должно быть вашего секрета. Именно поэтому платёжная ссылка — единственный способ принимать платежи без бэкенда: страницу на Tilda, Wix или в Notion можно подключить к оплате, ничего не подписывая.

Базовый URL: https://api.oblodai.com

---

​

GET /v1/link/{id}

Публичная карточка ссылки: что показывать покупателю и какой виджет суммы рисовать.

​

Параметры пути

Параметр	Описание
{id}	link_id из ответа POST /v1/payment/link.

​

Пример запроса

cURL

curl -s https://api.oblodai.com/v1/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40

import requests
r = requests.get("https://api.oblodai.com/v1/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40")
print(r.json())

const r = await fetch("https://api.oblodai.com/v1/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40");
console.log(await r.json());

​

Пример ответа

{
  "state": 0,
  "result": {
    "link_id": "5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40",
    "title": "Поддержать проект",
    "description": "Спасибо!",
    "amount_mode": "open",
    "currency": "USD",
    "amount_min": "1.00"
  }
}

Поле	Тип	Описание
link_id	string	Идентификатор ссылки.
title / description	string	Что показать покупателю.
amount_mode	string	fixed — сумму не спрашивать; open — поле ввода суммы (донат); range — поле ввода с границами.
currency	string	Валюта цены — в ней покупатель вводит сумму.
amount_fixed	string	Сумма при fixed.
amount_min / amount_max	string	Границы. Присутствуют, только если заданы.
pinned_currency / pinned_network	string	Если есть — монета и сеть уже закреплены, выбор покупателю не показывать. Если полей нет — рисуйте выбор монеты и сети.

Ответ намеренно не содержит ничего о мерчанте — ни идентификаторов, ни настроек, ни статистики. Его безопасно запрашивать из браузера.

​

Коды ошибок

Код	Значение
400 paylink.bad_id	{id} не является корректным UUID.
404 paylink.not_found	Ссылка не найдена, выключена или истекла.
503 paylink.disabled	Платёжные ссылки недоступны на этом шлюзе.

---

​

POST /v1/link/{id}/checkout

Создать по ссылке настоящий счёт для этого покупателя. Возвращает объект платежа — с uuid, адресом и ссылкой url на hosted‑страницу оплаты, куда покупателя и нужно отправить.

​

Параметры запроса

amount · string

Сумма, которую ввёл покупатель, в валюте цены ссылки. Обязательна для open и range; для fixed игнорируется (сумму задаёт ссылка).

currency · string

Валюта расчёта — монета, которой платит покупатель. Нужна, только если ссылка не закрепила pinned_currency.

network · string

Сеть расчёта. Нужна, только если ссылка не закрепила pinned_network.

payer_email · string

Email покупателя. На него автоматически уйдёт чек после оплаты.

Для fixed сумму можно не передавать вовсе. Если ссылка закрепила монету/сеть, переданные значения игнорируются — выигрывает закрепление.

Если не закрепила и покупатель ничего не выбрал, счёт создастся валюто‑агностичным: монету и сеть покупатель выберет уже на странице оплаты.

​

Пример запроса

cURL

curl -s https://api.oblodai.com/v1/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40/checkout \
  -X POST -H 'Content-Type: application/json' \
  -d '{"amount":"10.00","currency":"USDT","network":"tron","payer_email":"[e-mail]"}'

import requests
r = requests.post(
    "https://api.oblodai.com/v1/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40/checkout",
    json={"amount": "10.00", "currency": "USDT", "network": "tron",
          "payer_email": "[e-mail]"},
)
print(r.json()["result"]["url"])   # сюда отправляем покупателя

const r = await fetch(
  "https://api.oblodai.com/v1/link/5d3f2a71-9c84-4b0e-8d17-3e6a2c9f1b40/checkout",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ amount: "10.00", currency: "USDT", network: "tron", payer_email: "[e-mail]" }),
  },
);
const { result } = await r.json();
window.location = result.url;      // редирект на страницу оплаты

​

Пример ответа

Обычный объект платежа — точно такой же, как у POST /v1/payment:

{
  "state": 0,
  "result": {
    "uuid": "8b1d7d2e-2b0a-4a1f-9c3e-1f2a3b4c5d6e",
    "amount": "10.00",
    "currency": "USD",
    "payer_amount": "10.150000",
    "payer_currency": "USDT",
    "network": "tron",
    "address": "TJ4b1...C9xk",
    "address_qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "payment_status": "check",
    "is_multi": false,
    "url": "https://pay.oblodai.com/pay/8b1d7d2e-2b0a-4a1f-9c3e-1f2a3b4c5d6e",
    "expired_at": 1783728000
  }
}

Дальше — обычный платёж: покупатель платит, вы получаете вебхук.

​

Коды ошибок

Код	Значение
400 request.bad_json	Тело не парсится.
400 paylink.bad_id	{id} не является корректным UUID.
404 paylink.not_found	Ссылка не найдена, выключена или истекла.
400 paylink.amount_required	Режим open/range, а amount не передан.
400 paylink.not_positive	Сумма не положительная.
400 paylink.below_min	Сумма меньше amount_min.
400 paylink.above_max	Сумма больше amount_max.
400 paylink.bad_mode	У ссылки некорректный режим суммы.
400 paylink.unknown_currency	Неизвестная валюта.
503 paylink.disabled	Платёжные ссылки недоступны на этом шлюзе.

Кроме них может прийти любая ошибка создания счёта — checkout выполняет тот же путь, что и POST /v1/payment: payment.below_minimum, payment.network_required, payment.unsupported_network, invoice.quote_failed и т. д. Показывайте покупателю понятный текст и давайте повторить.

---

​

Нюансы

• Секрет в браузер не попадает. Оба метода публичные — этим ссылка и отличается от прямого создания счёта.
• Каждый checkout — новый счёт. Двое покупателей по одной ссылке получат разные uuid и разные адреса. Один и тот же покупатель, нажав дважды, тоже получит два счёта — идемпотентности здесь нет (её нечем ключевать: order_id покупатель не задаёт).
• Выключенная ссылка отдаёт 404 на обоих методах, но уже созданные по ней счета остаются оплачиваемыми.
• payer_email = чек. Если покупатель оставил email, после оплаты ему автоматически уйдёт чек. Прислать письмо со счётом («оплатите») можно и вручную — POST /v1/payment/send-email.

---

​

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

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

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

GET /v1/pay/{id}

POST /v1/pay/{id}/select

Объект платежа

POST /v1/payment/send-email