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

Разберём полный поток приёма платежа: от создания счёта до финального статуса, с объяснением, что происходит на каждом шаге и как на это реагировать.

Если нужен просто «завести за 5 минут» — см. Быстрый старт. Здесь — подробнее.

---

​

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

1. Вы создаёте счёт (POST /v1/payment)
        ↓  получаете uuid, адрес, ожидаемую сумму
2. Покупатель отправляет средства на адрес
        ↓
3. Шлюз видит транзакцию и набирает подтверждения сети
        ↓  (число зависит от суммы и сети)
4. Порог достигнут → счёт становится оплаченным
        ↓  вам приходит вебхук invoice.paid
5. Недоплата/переплата обрабатываются по вашим настройкам accuracy и autorefund

---

1. Создать счёт

   Python

   payment = call("/v1/payment", {
       "amount": "10",
       "currency": "USD",         # валюта ЦЕНЫ: USD, EUR, RUB… или монета
       "order_id": "order-1",     # ваш бизнес-ключ — задавайте всегда, он дедуплицирует
       "to_currency": "USDT",
       "network": "tron",
       "lifetime": 3600,
       "payer_email": "[e-mail]",   # необязательно: включает АВТОЧЕК после оплаты
   }, idempotency_key="pay-order-1")["result"]   # Idempotency-Key стабилен при ретраях — не генерируйте новый на каждую попытку
   

   const payment = (await call("/v1/payment", {
     amount: "10",
     currency: "USD",         // валюта ЦЕНЫ: USD, EUR, RUB… или монета
     order_id: "order-1",     // ваш бизнес-ключ — задавайте всегда, он дедуплицирует
     to_currency: "USDT",
     network: "tron",
     lifetime: 3600,
     payer_email: "[e-mail]",  // необязательно: включает АВТОЧЕК после оплаты
     // Idempotency-Key стабилен при ретраях — не генерируйте новый на каждую попытку; передаём третьим аргументом
   }, "pay-order-1")).result;
   

   Про два механизма защиты от дублей (Idempotency-Key + order_id) — Устойчивый клиент. Про авточек на payer_email — Счёт и чек на почту.

   Из ответа вам нужны:

   • address — адрес, на который платит покупатель;
   • payer_amount + payer_currency — сколько и в какой крипте нужно отправить;
   • url — ссылка на hosted‑страницу оплаты (можно просто отправить покупателя туда);
   • uuid — сохраните его в связке с вашим заказом;
   • payer_address — появляется после оплаты: адрес, с которого реально пришли деньги. Это дефолтный адрес возврата, поэтому возврат можно делать, не спрашивая адрес у покупателя.

   Полное описание полей — Объект платежа.

2. Показать адрес покупателю

   Два варианта:

   1. Отправить на hosted‑страницу по url — там уже есть адрес, QR, таймер и статус. Ничего рисовать не нужно.
   2. Показать у себя — возьмите address и address_qr_code (готовый data:‑URI QR) из ответа.

   Страница может отслеживать статус без секрета мерчанта — через публичный GET /v1/pay/{id}.

3. Дождаться оплаты

   Счёт проходит по статусам (payment_status):

   Статус	Что значит	Ваша реакция
   select	Валюто‑агностичный счёт (is_multi: true): покупатель ещё не выбрал монету и сеть. Адреса и payer_currency пока нет — это нормально.	Ничего, ждём выбора на странице оплаты. → Режим 3
   check	Счёт создан, ждём оплату.	Ничего, ждём.
   confirm_check	Транзакцию видим, ждём подтверждений.	Можно показать «платёж получен, подтверждается».
   wrong_amount_waiting	Пришла недоплата, срок ещё не вышел.	Ждём доплату (если разрешена).
   paid	Оплачено в пределах допуска.	Выдать товар/услугу.
   paid_over	Переплата сверх допуска.	Выдать; излишек вернётся, если включён автовозврат.
   wrong_amount	Недоплата, срок вышел.	Не выдавать; средства вернутся при автовозврате.
   cancel	Счёт истёк или отменён.	Закрыть заказ.

   Терминальные статусы (is_final: true): paid, paid_over, wrong_amount, истёкшие/отменённые.

4. Реагировать на вебхук, а не опрашивать

   Правильный способ узнать об оплате — вебхук invoice.paid, а не постоянный опрос /info. Настройте приёмник по инструкции Настройка вебхуков. Опрос POST /v1/payment/info держите как резервный механизм.

   Ключевое правило обработки: дедуплицируйте по uuid + status и выдавайте товар только один раз — вебхук может прийти повторно.

---

​

Важные нюансы

• Курс фиксируется при создании и действует до rate_expires_at. Для долгоживущих ссылок курс лениво перезапрашивается при открытии страницы, пока счёт не оплачен и не истёк. После начала оплаты адрес и сумма не меняются.
• Минимум сети. На дорогих сетях (Ethereum, Bitcoin) есть минимальная сумма; платёж ниже вернёт payment.below_minimum уже при создании.
• Подтверждения зависят от суммы. Крупный платёж требует больше подтверждений (reorg‑безопасность), мелкий — меньше.
• Идемпотентность — два механизма. HTTP‑заголовок Idempotency-Key (одинаковый во всех попытках одного действия; повтор вернёт тот же ответ и Idempotent-Replayed: true) и order_id (ваш бизнес‑ключ: повтор создания с тем же order_id вернёт существующий живой счёт, а не создаст второй). См. Идемпотентность.

---

​

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

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

а что, если не фиксировать валюту заранее?

Недоплата, переплата и автовозврат

как настроить допуски.

Статические кошельки

постоянный адрес вместо разовых счетов.

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

принять платёж вообще без бэкенда.

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

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

Массовые операции

создать до 5000 счетов одним запросом.