Страница оплаты

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

Главное правило

Не отдавайте товар по редиректу. Получив покупателя на return_url, проверьте подпись, затем запросите инвойс GET /v1/invoices/{id} и отдавайте товар только по ответу API — так же, как после вебхука.

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

Как это работает

1. Продукт создаёт инвойс: POST /v1/invoices. Поле ответа checkout_url — ссылка на страницу оплаты этого инвойса. Если в установке нет страницы оплаты, поле равно null — см. инвойсы.
2. Продукт отправляет покупателя по checkout_url.
3. У инвойса, созданного без asset, страница сначала даёт покупателю выбрать сеть, затем монету — см. выбор токена. Затем показывает сумму, адрес и статус и обновляет их, пока покупатель платит.
4. Когда у инвойса появляется исход, страница отправляет покупателя на адрес возврата или отмены мерчанта с параметрами и подписью. Пока инвойс не оплачен, кнопка «Вернуться в магазин» ведёт на адрес отмены с теми же параметрами и подписью.
5. Продукт проверяет подпись и берёт статус из API.

Вебхуки при этом приходят так же, как без страницы.

Страница для покупателя

Страница открывается по checkout_url без входа и без ключей. Другой сайт не может встроить её во фрейм, и страница не передаёт сайту мерчанта Referer.

В статусе created страница показывает:

• название мерчанта;
• статус «Ожидаем оплату»;
• время до срока оплаты;
• сумму к оплате — amount_expected — с тикером и сетью, с кнопкой копирования;
• сеть: её знак по network_icon_slug, название network_name и стандарт её токенов token_standard, например «BNB Smart Chain · Токен BEP-20». У нативной монеты сети — BNB, ETH, TRX, GRAM, SOL — стандарта токенов нет: она не токен, и строки «Токен …» страница не показывает;
• под «Подробнее», свёрнуто: курс котировки; если комиссию сервиса платит покупатель — разбивку «Цена · Комиссия сервиса · Итого»: amount_requested, комиссию со ставкой и amount_expected; показанная комиссия — amount_expected минус amount_requested;
• там же — уже полученную сумму, если amount_received больше нуля;
• предупреждение отправлять ровно этот актив и в этой сети, одной строкой вместе с тем, что комиссия сети — сверх суммы;
• QR-код;
• адрес целиком, с кнопкой копирования;
• в TON — кнопку «Открыть в кошельке»: ссылку wallet_url, которая открывает приложение кошелька с уже заполненными адресом, суммой и токеном;
• кнопку «Вернуться в магазин», если у инвойса или проекта есть адрес отмены.

Сумма, сеть и адрес стоят в одной карточке друг под другом. Адрес занимает свою строку во всю ширину карточки, кнопка копирования рядом с ним — значок; в колонке шириной 512 px адрес до 48 знаков помещается в одну строку, на узком экране переносится. QR-код стоит под адресом. На экране меньше 640 px он скрыт за кнопкой «Показать QR-код»: телефон не сканирует собственный экран; на экране шире код показан сразу. Время до срока — справа в строке с названием мерчанта.

Суммы страница пишет без нулей в конце: 49.900000 показывается и копируется как 49.9.

Когда на инвойс пришли переводы, страница перечисляет их под заголовком «Полученные переводы»: сумма, подтверждения из нужных, хэш транзакции целиком с кнопкой копирования и ссылка на транзакцию в обозревателе сети. Ссылку страница показывает, только если это адрес https; без неё остаётся хэш.

QR-код содержит только адрес. Кошелёк, считавший его, не получает ни суммы, ни токена. Поэтому сумма показывается и копируется отдельно, а страница просит покупателя сверить адрес целиком после вставки. Адрес нигде не сокращается. В TON кнопка «Открыть в кошельке» передаёт ещё и сумму с токеном — ссылкой ton://transfer из документации TON; покупатель всё равно сверяет их в кошельке перед подтверждением.

Страница бывает на английском и на русском. Чтобы открыть её на нужном языке, добавьте к checkout_url параметр lang: ?lang=en или ?lang=ru; страница запоминает этот выбор в cookie. Без параметра страница берёт по порядку запомненный выбор, язык браузера и английский. Переключить язык покупатель может внизу страницы.

Страница сама обновляет статус, перезагружать её не нужно:

• первый запрос — через 3 секунды, второй — через 5, дальше каждые 10;
• после смены статуса отсчёт начинается заново с 3 секунд;
• пока вкладка скрыта, запрос идёт раз в 30 секунд;
• когда покупатель возвращается на вкладку, следующий запрос идёт через 3 секунды;
• неудачный запрос не меняет экран, и страница продолжает спрашивать.

Время до срока считается по часам сервера страницы, а не устройства покупателя. Без JavaScript страница не обновляется, не ведёт отсчёт, не копирует и не переводит на сайт.

Что страница показывает по статусам:

В статусе с исходом — confirmed, settled, paid_late, underpaid или expired — страница скрывает сумму, адрес и QR-код и перестаёт обновляться. Список переводов остаётся, а вместо адреса появляется ссылка на адрес оплаты в обозревателе сети. Дальше:

• Есть адрес нужного вида (см. адреса возврата) — страница отсчитывает 5 секунд и переводит покупателя на сайт мерчанта. Кнопка переводит сразу: «Перейти в магазин» — на адрес возврата, «Вернуться в магазин» — на адрес отмены. Прямо перед переходом страница запрашивает заново подписанный адрес, а не берёт полученный раньше; если запрос не удался, страница останавливается и просит нажать кнопку ещё раз. Так же страница ведёт себя, если покупатель открыл её у инвойса, у которого исход уже есть.
• Адреса нужного вида нет — страница показывает исход и оставляет покупателя на месте.

Пока у инвойса нет исхода, страница никуда не переводит покупателя сама. Кнопка «Вернуться в магазин» при нажатии запрашивает заново подписанный адрес отмены. Если за это время у инвойса появился исход, страница показывает его вместо перехода, а затем переводит, как при любом исходе.

expired и underpaid ещё могут смениться на paid_late, если деньги придут позже. Покупатель, открывший страницу снова, увидит новый статус; мерчант получит вебхук invoice.paid_late.

Несуществующий инвойс и инвойс отключённого мерчанта показывают одинаковую страницу «Счёт не найден». Страница ограничивает число запросов с одного IP-адреса в минуту и сверх лимита показывает «Слишком много запросов».

Выбор токена

Инвойс, созданный без asset (инвойсы), пока его статус created, открывается экраном выбора. Сверху — название мерчанта и время до срока, под ними одной строкой сумма заказа в USD. Дальше:

1. Сеть — выпадающий список сетей, в которых API предлагает хотя бы один актив: знак и название из каталога. Сеть не выбирается заранее.
2. Монета — второй выпадающий список, доступный после выбора сети: только активы выбранной сети, каждый с каталожной иконкой, тикером и суммой к оплате из API по текущему курсу. Даже единственная монета требует явного выбора. Смена сети сбрасывает выбранную монету; совпадающий тикер не переносит выбор в другую сеть.
3. Сводка — одна строка «К оплате»: сумма в выбранной монете и название сети; под ней мелко курс и, если комиссию сервиса платит покупатель, её ставка. Ниже одна строка: отправлять только эту монету в этой сети. Суммы разбивки «Цена · Комиссия сервиса · Итого» страница показывает после выбора, под «Подробнее».

Экран не добавляет нативные монеты или другие активы, которых нет в choices: поддержка способа оплаты определяется ядром, а не наличием иконки.

Кнопка «Перейти к оплате» сохраняет выбор, и страница показывает экран оплаты, описанный выше. Кнопка видна на экране любой высоты: если конец формы ниже края экрана, кнопка прилипает к нижнему краю. Под кнопкой — строка о том, что после этого шага монету и сеть сменить нельзя.

• Показанные и записанные суммы. Сумму каждой монеты страница показывает по курсу, который API вернул вместе с ней, и отправляет rate_id этого курса вместе с выбором. Сервис записывает ровно показанную сумму, пока этот курс ещё свежий; иначе переводит цену по последнему свежему курсу. После выбора страница показывает записанную сумму. В токене, привязанном к доллару США, записанная сумма действует до дедлайна инвойса; в любом другом токене остаток долга может пересчитаться после окна котировки — см. окно котировки.
• Выбор окончательный. Повторное нажатие с тем же токеном ничего не меняет. Если уже выбран другой токен, например в другой вкладке, страница показывает экран оплаты в этом токене с пометкой, что сменить его нельзя.
• Другая вкладка. Экран выбора раз в 10 секунд проверяет инвойс и перезагружается, если токен выбран или статус уже не created.
• Срок. Когда время до срока доходит до нуля, экран сообщает, что срок вышел, и выключает кнопку. Когда сервис переводит инвойс в expired, страница перезагружается, показывает «Срок оплаты истёк» и переводит на адрес отмены, если он есть.
• Выбрать нечего. Если ни один актив нельзя предложить — магазин сейчас не принимает ни одного из них, мерчант не одобрен, платформа приостановила режим адресов магазина или срок вышел, — страница сообщает, что оплатить сейчас нельзя, и просит не отправлять деньги. Разрешённая монета, курс которой сейчас не свежий, не предлагается, пока курс снова не станет свежим; этот случай API отмечает полем rates_unavailable.
• Токен стал недоступен к моменту нажатия — страница просит выбрать другой. Если сохранить выбор не удалось по другой причине, страница просит попробовать ещё раз через минуту.
• Без JavaScript интерактивный селектор скрыт; работает обычная форма с группами по сетям и вариантами монет с суммами внутри каждой группы.

Адреса возврата

Какой адрес получает покупатель, зависит от статуса инвойса:

Адреса проекта задаются в настройках проекта в кабинете — «После успешной оплаты» это адрес возврата, «Вернуться в магазин / при неудаче» — адрес отмены — или оператором. Пустое поле означает, что адреса нет. Без адреса нужного вида редиректа нет, а без адреса отмены нет и кнопки «Вернуться в магазин».

Для отдельного инвойса адрес можно переопределить полями return_url и cancel_url в POST /v1/invoices или в форме счёта в кабинете. Переопределение допускается, если его origin — схема, хост и порт — совпадает с origin одного из этих адресов проекта:

• адреса того же вида из настроек проекта;
• сайта проекта из заявки на проект.

Например, при сайте проекта https://shop.example допустимо https://shop.example/orders/1001/paid, а https://pay.shop.example/… и https://shop.example:8443/… — нет. На общих хостах t.me и telegram.me под одним origin живут разные боты и каналы, поэтому там совпасть должен и первый сегмент пути — имя бота или канала, без учёта регистра. При сайте проекта https://t.me/example_shop_bot допустимо https://t.me/example_shop_bot?start=paid_1001, а https://t.me/other_bot — нет. Адрес проекта на общем хосте без имени в пути, например https://t.me, не допускает ничего.

Если совпадения нет или у проекта нет ни адреса того же вида, ни сайта, ответ — 422 redirect_url_not_allowed, и сообщение называет допустимые origin. Адреса проекта меняются в кабинете или оператором, но никогда ключом API: утёкший ключ не отправит покупателей на сайт или к боту, которых нет в проекте.

Требования к любому адресу возврата или отмены:

• начинается с https:// в нижнем регистре;
• без символа @ и без пробелов — так в адрес не попадают логин и пароль;
• не длиннее 2000 символов;
• без параметров invoice_id, order_id, status, ts и signature: их добавляет сервис.

Остальные параметры и фрагмент сохраняются как есть. Используется переопределение инвойса, если оно есть, иначе адрес проекта на момент редиректа: смена адреса проекта сразу касается инвойсов без переопределения.

Переход до исхода

На адрес отмены покупатель может прийти, пока инвойс открыт: со status=created, status=seen или status=partially_paid, если нажал «Вернуться в магазин». Такой инвойс ещё может быть оплачен; при seen перевод уже замечен в сети, а при partially_paid часть суммы уже пришла. Не отменяйте заказ по такому переходу: статус берите из GET /v1/invoices/{id} и вебхуков, как после любого редиректа.

Если вы переходите с Heleket

Адреса в инвойсе допускаются только в пределах сайтов проекта — см. адреса возврата. К каждому редиректу сервис добавляет параметры и подпись, описанные ниже.

Параметры редиректа

Значения закодированы по правилам query-строки: читайте их через URLSearchParams или аналог, а не разбором строки вручную.

Подпись

Подпись — HMAC-SHA256 в hex с секретом вебхуков мерчанта в качестве ключа. Подписывается строка из пяти строк, соединённых символом перевода строки \n (байт 0x0A), без перевода строки в конце:

redirect
<ts>
<invoice_id>
<status>
<order_id>

Разделитель — перевод строки, а не точка, потому что order_id может содержать точки, а перевод строки не может содержать ни одно поле. Первая строка redirect не даёт подписи редиректа сойти за подпись вебхука тем же секретом.

Получатель обязан:

• отклонять редирект, если ts отличается от текущего времени больше чем на 300 секунд (5 минут);
• сравнивать подписи за постоянное время;
• проверять, что invoice_id — это инвойс заказа order_id, и брать статус из API, а не из параметра.

Проверка на Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

// query — URLSearchParams запроса, пришедшего на return_url или cancel_url.
export function verifyRedirect({ query, secret, nowMs = Date.now() }) {
  const fields = ["ts", "invoice_id", "status", "order_id"].map((name) => query.get(name));
  const signature = query.get("signature");
  if (fields.some((value) => value === null || value.includes("\n")) || signature === null) return false;
  const [ts, invoiceId, status, orderId] = fields;
  if (!/^\d{1,12}$/.test(ts) || !/^[0-9a-f]{64}$/.test(signature)) return false;
  if (Math.abs(nowMs / 1000 - Number(ts)) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret)
    .update(["redirect", ts, invoiceId, status, orderId].join("\n"))
    .digest();
  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}

Функция возвращает true только для неизменённого адреса, подписанного этим секретом не раньше чем 300 секунд назад. Секрет вебхуков показывается один раз, при создании проекта в кабинете, — см. вебхуки.

Пример для проверки своей реализации. При секрете example-webhook-secret и параметрах ts=1789300000, invoice_id=6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44, status=confirmed, order_id=ord_1001 подпись равна 2af98109e8fad432cc8e511f5e73f542ed3be8913b8d2863fe360f5f31f8e651.

Маршруты страницы оплаты

Два маршрута ниже — не для мерчантов. Их вызывает сервер страницы оплаты по приватной сети: из интернета они недоступны и в описании OpenAPI их нет.

• Без ключа API. Страницу открывает покупатель, у которого ключа нет; инвойс открывается его идентификатором — случайным UUID, который доходит до покупателя внутри checkout_url.
• Отключённый мерчант. Его инвойсов для этих маршрутов не существует (404 invoice_not_found): страница не должна продолжать собирать деньги мерчанту, которого выключил оператор или владелец.
• Кэширование. Успешный ответ содержит Cache-Control: no-store: в нём подписанные адреса.
• Лимит запросов. Запросы с одного IP-адреса ограничены в окне 60 секунд тем же значением, что лимит по IP у /v1, но отдельным счётчиком. Все запросы страницы приходят с адреса её сервера, поэтому этот лимит защищает API, но не разделяет покупателей: покупателей ограничивает сама страница.

Прочитать инвойс для страницы

GET /checkout/v1/invoices/{id} возвращает инвойс в том виде, в каком его показывает страница оплаты.

Запрос

Ответ

200. Все поля присутствуют всегда; поле, которое не применимо, равно null.

Поля элемента choices:

Знаки актива и сети независимы. Страница не угадывает знак токена по symbol: неизвестный slug даёт нейтральный знак. Отсутствующий в ответе старого API или некорректный asset_icon_slug страница читает как null, не блокируя оплату.

Подписанные адреса в redirect и back_url собираются в момент запроса, и ts в них — этот момент. В ответ не попадают идентификатор мерчанта, его секреты, external_user_id, order_id отдельным полем и amount_credited: номер заказа доходит до покупателя только внутри подписанного адреса.

Ошибки

Пример

GET /checkout/v1/invoices/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44

200 — оплаченный инвойс, у проекта которого есть адрес возврата:

{
  "invoice_id": "6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "merchant_name": "Shop",
  "status": "confirmed",
  "asset": "USDT_TRON",
  "asset_icon_slug": "usdt",
  "symbol": "USDT",
  "network": "tron",
  "network_name": "TRON",
  "network_icon_slug": "tron",
  "token_standard": "TRC-20",
  "address": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "address_explorer_url": "https://tronscan.org/#/address/TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "wallet_url": null,
  "price": null,
  "choices": null,
  "rates_unavailable": false,
  "quote": null,
  "amount_requested": "49.900000",
  "amount_expected": "49.900000",
  "amount_received": "49.900000",
  "amount_remaining": "0.000000",
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": "0.000000", "amount": "0.499000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "expires_at": "2026-09-11T21:03:05.531Z",
  "confirmations_required": 20,
  "confirmation_estimate": null,
  "deposits": [
    {
      "tx_hash": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c",
      "amount": "49.900000",
      "confirmations": 20,
      "status": "confirmed",
      "explorer_url": "https://tronscan.org/#/transaction/50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
    }
  ],
  "redirect": {
    "kind": "return",
    "url": "https://shop.example/thanks?invoice_id=6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44&order_id=ord_1001&status=confirmed&ts=1789300000&signature=2af98109e8fad432cc8e511f5e73f542ed3be8913b8d2863fe360f5f31f8e651"
  },
  "back_url": null
}

200 — инвойс без токена, покупатель которого платит комиссию сервиса 1%, а у проекта нет адреса отмены, при курсе USDT 0.9991 USD:

{
  "invoice_id": "3b9e5c2a-7d41-4f6b-8a2e-5c1d9f0b7e63",
  "merchant_name": "Shop",
  "status": "created",
  "asset": null,
  "asset_icon_slug": null,
  "symbol": null,
  "network": null,
  "network_name": null,
  "network_icon_slug": null,
  "token_standard": null,
  "address": null,
  "address_explorer_url": null,
  "wallet_url": null,
  "price": { "amount": "100.000000", "currency": "USD" },
  "choices": [
    {
      "asset": "USDT_TRON",
      "asset_icon_slug": "usdt",
      "network": "tron",
      "network_name": "TRON",
      "network_icon_slug": "tron",
      "token_standard": "TRC-20",
      "symbol": "USDT",
      "decimals": 6,
      "amount_requested": "100.090082",
      "amount_expected": "101.090983",
      "min_amount": "1.000000",
      "rate": "0.999100000000000000",
      "rate_id": "48213",
      "rate_expires_at": "2026-09-16T12:05:00.000Z"
    }
  ],
  "rates_unavailable": false,
  "quote": null,
  "amount_requested": null,
  "amount_expected": null,
  "amount_received": null,
  "amount_remaining": null,
  "fees": {
    "service": { "payer": "customer", "percent": "1.00", "fixed": null, "amount": null },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "expires_at": "2026-09-11T21:03:05.531Z",
  "confirmations_required": null,
  "confirmation_estimate": null,
  "deposits": [],
  "redirect": null,
  "back_url": null
}

API отдаёт плоский список активов, у каждого своя сеть; группировать их по монете — дело страницы.

Сохранить выбор токена

POST /checkout/v1/invoices/{id}/select записывает токен, который покупатель выбрал для инвойса, созданного без asset. Сервер страницы вызывает его, когда покупатель нажимает «Перейти к оплате».

Запрос

id в пути — invoice_id. Тело — JSON-объект с Content-Type: application/json; поле, которого нет в таблице, отклоняется с 400 validation_failed.

Ответ

200 с инвойсом в формате чтения инвойса для страницы — уже с токеном, адресом, суммами и quote и с choices, равным null.

• Выбор окончательный. Повторный запрос с тем же активом возвращает инвойс без изменений, даже после срока, поэтому запрос, ответ на который потерялся, безопасно повторить. Другой актив получает 409 asset_already_selected. То же у инвойса, созданного с asset.
• Одновременные запросы обрабатываются по одному: первый записывает свой актив, остальные получают 200 или 409 asset_already_selected по правилу выше.
• Когда выбор возможен: статус created, и часы сервиса не дошли до expires_at.
• Проверки — по порядку, с теми же кодами, что при создании инвойса: мерчант одобрен; платформа не приостановила его режим адресов; актив есть в currencies инвойса, если у инвойса есть список; актив принимается к оплате; включён оператором и в настройках проекта; у него есть курс, и курс свежий; цена, переведённая по этому курсу, не меньше его минимального депозита.
• Курс. С rate_id цена переводится по этому курсу, если это принятый курс монеты этого актива и он ещё свежий. Иначе, как и без rate_id, — по последнему свежему курсу монеты. rate_id другой монеты или старый не ошибка: он просто не используется. Выбор записывает первую котировку, её показывает quote ответа, — см. цену и курс.
• Условия. Ставка комиссии и плательщики — записанные при создании инвойса; фиксированная часть комиссии — та, что у актива в момент выбора. amount_expected считается от переведённой цены так же, как у инвойса, созданного в этом активе.
• Адрес. Мерчанту per_invoice выводится новый адрес, мерчанту per_user — постоянный адрес пользователя из external_user_id.

Ошибки

Пример

POST /checkout/v1/invoices/3b9e5c2a-7d41-4f6b-8a2e-5c1d9f0b7e63/select
Content-Type: application/json

{"asset": "USDT_TRON", "rate_id": "48213"}

200 — инвойс без токена из предыдущего примера после выбора по показанному курсу:

{
  "invoice_id": "3b9e5c2a-7d41-4f6b-8a2e-5c1d9f0b7e63",
  "merchant_name": "Shop",
  "status": "created",
  "asset": "USDT_TRON",
  "asset_icon_slug": "usdt",
  "symbol": "USDT",
  "network": "tron",
  "network_name": "TRON",
  "network_icon_slug": "tron",
  "token_standard": "TRC-20",
  "address": "TSeJkUh4Qv67VNFwY8LaAxERygNdy6NQZK",
  "address_explorer_url": "https://tronscan.org/#/address/TSeJkUh4Qv67VNFwY8LaAxERygNdy6NQZK",
  "wallet_url": null,
  "price": { "amount": "100.000000", "currency": "USD" },
  "choices": null,
  "rates_unavailable": false,
  "quote": { "rate": "0.999100000000000000", "currency": "USD", "expires_at": "2026-09-11T21:03:05.531Z" },
  "amount_requested": "100.090082",
  "amount_expected": "101.090983",
  "amount_received": "0.000000",
  "amount_remaining": "101.090983",
  "fees": {
    "service": { "payer": "customer", "percent": "1.00", "fixed": "0.000000", "amount": "0.000000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "expires_at": "2026-09-11T21:03:05.531Z",
  "confirmations_required": 20,
  "confirmation_estimate": null,
  "deposits": [],
  "redirect": null,
  "back_url": null
}