Выплатные ссылки (крипто-чеки)

Зарезервируйте выплату без адреса получателя — он сам заберёт средства по ссылке.

Методы: /v1/payout/link · /batch · /list · /info · /cancel

Выплатная ссылка (крипто-чек) — способ отправить средства, не зная адреса получателя. Вы резервируете сумму (available → payout_held на балансе), получаете одноразовую ссылку claim_url и передаёте её получателю (можно письмом — поле email). Получатель открывает страницу, вводит свой адрес — и из резерва рождается обычная выплата. Невостребованная ссылка возвращает резерв при истечении срока или отмене.

URL: https://api.oblodai.com/v1/payout/link · Аутентификация: обязательна, payout-ключ · Идемпотентность: заголовок Idempotency-Key здесь не действует — дедупликация через поле reference (уникально на мерчанта).

Примеры используют хелпер call() и переменные $SECRET/$PUBLIC_ID — их определение см. в Как подписать запрос. Проще не писать подпись руками, а взять SDK.

​

Статусы ссылки

Статус	Значение
funded	Создана, резерв удержан, ждёт получателя
claiming	Получатель ввёл адрес, выплата порождается (транзиентный)
claimed	Выплата порождена (payout_id заполнен) — терминальный
expired	Срок вышел без claim; резерв возвращён — терминальный
cancelled	Отменена мерчантом до claim; резерв возвращён — терминальный

​

POST /v1/payout/link

Создаёт одну ссылку. Под row-lock проверяется достаточность зрелого баланса (действует maturity-гейт, как у обычной выплаты).

​

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

currency · string · обязательно

Крипто-актив выплаты (USDT, BTC, …). Фиат невозможен.

network · string · обязательно

Сеть выплаты получателю (tron, bitcoin, …).

amount · string · обязательно

Сумма в currency, строкой. Больше нуля.

reference · string

Ваш ключ дедупликации, уникальный на мерчанта. Настоятельно рекомендуется: заголовок Idempotency-Key на этом эндпоинте не действует. См. предупреждение ниже.

title · string

Заголовок — виден получателю на странице получения.

note · string

Сообщение получателю (видно на странице и в письме).

email · string

Если задан — получателю уходит письмо с кнопкой «Получить средства» (best-effort: ошибка доставки не отменяет создание ссылки).

expires_in_hours · int64

Срок жизни ссылки в часах, клампится в диапазон 1–720 (30 дней).

Задавайте expires_in_hours явно. Если поле не передано (или передан 0), ссылка живёт всего 1 час — значение приводится к нижней границе диапазона, а не к максимуму.

Повтор с тем же reference сейчас возвращает 500, а не повтор ответа: уникальный индекс срабатывает без graceful-реплея. Не ретрайте создание вслепую — сначала проверьте /v1/payout/link/list, появилась ли ссылка. В батче дубликат фейлит только свой элемент.

​

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

cURL

BODY='{"currency":"USDT","network":"tron","amount":"25","reference":"bonus-42","title":"Бонус","note":"Спасибо за участие","email":"[e-mail]","expires_in_hours":168}'
TS=$(date +%s)
SIGSTR=$(printf '%s\n%s\n%s\n%s' "$TS" 'POST' '/v1/payout/link' "$BODY")
SIG=$(printf '%s' "$SIGSTR" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -s https://api.oblodai.com/v1/payout/link \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-Public-Id: $PUBLIC_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

call("/v1/payout/link", {
    "currency": "USDT", "network": "tron", "amount": "25",
    "reference": "bonus-42",              # ваш ключ дедупликации
    "title": "Бонус", "note": "Спасибо за участие",
    "email": "[e-mail]",          # получателю уйдёт письмо со ссылкой
    "expires_in_hours": 168,              # 7 дней; без поля будет ровно 1 час!
})

await call("/v1/payout/link", {
  currency: "USDT", network: "tron", amount: "25",
  reference: "bonus-42",                // ваш ключ дедупликации
  title: "Бонус", note: "Спасибо за участие",
  email: "[e-mail]",            // получателю уйдёт письмо со ссылкой
  expires_in_hours: 168,                // 7 дней; без поля будет ровно 1 час!
});

​

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

{
  "state": 0,
  "result": {
    "link_id": "7f0c9c2e-6c2a-4c1e-9f3a-1b2c3d4e5f60",
    "status": "funded",
    "amount": "25",
    "currency": "USDT",
    "network": "tron",
    "title": "Бонус",
    "note": "Спасибо за участие",
    "reference": "bonus-42",
    "email": "[e-mail]",
    "expires_at": "2026-07-22T17:00:00Z",
    "created_at": "2026-07-15T17:00:00Z",
    "claim_token": "Xk3v…43-символа…",
    "claim_url": "https://pay.oblodai.com/claim/Xk3v…"
  }
}

claim_token и claim_url возвращаются только здесь, один раз. Токен хранится у нас лишь хешем (SHA-256) — восстановить ссылку потом невозможно. Сохраните claim_url сразу.

​

POST /v1/payout/link/batch

До 500 ссылок одним запросом: {"links": [<элементы как в create>, …]}. Каждый элемент резервируется в своей транзакции — плохой элемент фейлит только себя. Все ссылки вызова получают общий batch_id.

Ответ (index-aligned)

{
  "state": 0,
  "result": {
    "created": 2,
    "total": 3,
    "results": [
      { "ok": true,  "link": { "link_id": "…", "claim_url": "…", "batch_id": "…" } },
      { "ok": false, "error": "payoutlink.insufficient_funds", "message": "available balance is less than the link amount" },
      { "ok": true,  "link": { "…": "…" } }
    ]
  }
}

Ошибки уровня запроса: payoutlink.empty_batch (400), payoutlink.batch_too_large (400, больше 500).

​

POST /v1/payout/link/list

Запрос: {"limit": 50, "offset": 0} (limit вне 1–200 → 50). Сортировка — новые первыми. Ответ: {"links": [ … ]} — без claim_token/claim_url.

​

POST /v1/payout/link/info

Запрос: {"link_id": "<uuid>"}. После claim в ответе появляются payout_id и claim_address.

​

POST /v1/payout/link/cancel

Запрос: {"link_id": "<uuid>"}. Отменяется только funded-ссылка: резерв возвращается (payout_held → available), статус — cancelled. Если получатель успел завершить claim конкурентно, вернётся ссылка со статусом claimed и payout_id — деньги уже ушли, двойного возврата не бывает.

​

Коды ошибок

payoutlink.unknown_currency · 400

Неизвестный крипто-актив. Повтор: Нет — проверьте пару валюта/сеть.

payoutlink.bad_amount · 400

Некорректная сумма. Повтор: Нет.

payoutlink.insufficient_funds · 409

Недостаточно доступного баланса. Повтор: Да, после пополнения.

payoutlink.funds_maturing · 409

Средства ещё дозревают. Повтор: Да, позже с backoff — как у выплат.

payoutlink.empty_batch · 400

Пустой массив links. Повтор: Нет.

payoutlink.batch_too_large · 400

Больше 500 элементов — разбейте на страницы. Повтор: Нет.

payoutlink.bad_id · 400

Некорректный link_id. Повтор: Нет.

payoutlink.not_found · 404

Ссылка не найдена (или чужая). Повтор: Нет — сверьте link_id.

payoutlink.not_funded · 409

Отменить можно только невостребованную (funded) ссылку. Повтор: Нет — проверьте статус через /info.

payoutlink.disabled · 503

Функция выключена на шлюзе. Повтор: Нет — обратитесь в поддержку.

​

Нюансы

• Письмо получателю — брендовый шаблон с кнопкой «Получить средства», текст note включается в письмо. Отправка best-effort: сбой почты не отменяет резерв.
• Поллеры: истечение проверяется раз в 60 секунд; «зависший» claim (статус claiming дольше 15 минут) добирается рипером — либо финализируется в claimed, либо откатывается в funded.
• Вебхуки: отдельных событий у ссылок нет. Когда получатель забирает средства, порождённая выплата шлёт обычные payout.* события; её order_id = payoutlink:<link_id> — так вы сопоставите событие со ссылкой.
• Баланс: резерв виден как удержание payout_held; available уменьшается в момент создания ссылки. См. Модель баланса.

​

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

Публичное получение по ссылке

Гайд: крипто-чеки

Создание выплаты

Объект Payout