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

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

Справочник объекта — Объект кошелька.

---

​

Инвойс, платёжная ссылка или статический кошелёк?

Способов принять деньги три, и выбор между ними определяется двумя вопросами: кто называет сумму и есть ли у вас бэкенд.

	Инвойс	Платёжная ссылка	Статический кошелёк
Метод	/v1/payment	/v1/payment/link	/v1/wallet
Сумма	Задаёте вы.	Вы или покупатель (open/range).	Любая, сколько прислали.
Срок	Ограничен.	Бессрочная или с TTL.	Бессрочный.
Нужен ли бэкенд	Да, на каждый заказ.	Нет — создали один раз.	Да, адрес на клиента.
Оплата	Закрывает конкретный счёт.	Каждая оплата — свой платёж.	Зачисляется на баланс.
Комиссия платформы	Удерживается.	Удерживается.	Удерживается (по вашей ставке).
Вебхук	invoice.* (type payment).	invoice.* (type payment).	wallet.paid (type wallet).
Сценарий	Разовая покупка в магазине.	Донаты, продажи без сайта, сайт на конструкторе.	Пополнение баланса, депозиты.

Коротко:

• Знаете сумму и есть бэкенд → инвойс.
• Бэкенда нет (Tilda/Wix, соцсети) или сумму называет плательщик (донаты) → платёжная ссылка.
• Нужен постоянный адрес за клиентом, а суммы произвольные → статический кошелёк (эта страница).

---

​

Персональный адрес для клиента

Тройка (currency, network, order_id) идемпотентна. Передайте order_id = идентификатор клиента — и получите его персональный постоянный адрес. Повторный вызов с той же тройкой вернёт тот же адрес.

Python

def deposit_address(client_id: str) -> str:
    w = call("/v1/wallet", {
        "currency": "USDT",
        "network": "tron",
        "order_id": client_id,   # закрепляет адрес за клиентом
    })["result"]
    return w["address"]

# Один и тот же клиент всегда получит один и тот же адрес
addr = deposit_address("client-42")

async function depositAddress(clientId) {
  const w = (await call("/v1/wallet", {
    currency: "USDT",
    network: "tron",
    order_id: clientId,   // закрепляет адрес за клиентом
  })).result;
  return w.address;
}

// Один и тот же клиент всегда получит один и тот же адрес
const addr = await depositAddress("client-42");

---

​

Приём пополнений

Каждое поступление на кошелёк порождает вебхук wallet.paid:

{
  "type": "wallet",
  "uuid": "0e5b6b9a-…",
  "order_id": "client-42",
  "address": "TXk9...c3Fd",
  "network": "tron",
  "currency": "USDT",
  "payment_amount": "150.00",
  "status": "paid",
  "is_final": true
}

Обрабатывайте его так же, как платёжный вебхук: проверьте подпись, дедуплицируйте по uuid + status. См. Настройка вебхуков и Объект вебхука.

payment_amount — это сумма, пришедшая на адрес (брутто), ДО нашей комиссии. На ваш баланс зачисляется нетто — за вычетом комиссии платформы (по умолчанию ~1.5%). Если вы кредитуете конечного клиента, начисляйте ему нетто (или заранее заложите комиссию в свою экономику), иначе начислите больше, чем реально легло на баланс. Точную удержанную сумму сверяйте по своему балансу (POST /v1/balance).

---

​

Блокировка и возврат

Если нужно перестать принимать на адрес — заблокируйте его:

Python

call("/v1/wallet/block", {"address": "TXk9...c3Fd"})            # заблокировать
call("/v1/wallet/block", {"address": "TXk9...c3Fd", "is_force_block": False})  # разблокировать

await call("/v1/wallet/block", { address: "TXk9...c3Fd" });            // заблокировать
await call("/v1/wallet/block", { address: "TXk9...c3Fd", is_force_block: false });  // разблокировать

is_force_block по умолчанию true. Чтобы снять блокировку, явно передайте false.

Средства, полученные на (обычно заблокированный) кошелёк, можно вывести на один адрес через POST /v1/wallet/blocked-address-refund — вернётся чистая сумма за вычетом газа.

---

​

Нюансы

• Комиссия платформы удерживается и с пополнений на статический кошелёк — по вашей ставке (по умолчанию ~1.5%, та же, что и на инвойсе). На баланс попадает нетто. Поэтому «гонять» продажи через статические кошельки ради экономии на комиссии смысла нет: ставка та же. Статические кошельки — для пополнений/депозитов (напр. балансы пользователей); для разовых продаж используйте инвойс (/v1/payment) — он даёт сумму, срок и статус конкретного заказа.
• Пара (currency, network) должна быть поддерживаемым методом.
• Для каждого клиента используйте уникальный order_id — иначе они будут делить один адрес.

---

​

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

POST /v1/wallet

Объект кошелька

POST /v1/wallet/block

POST /v1/wallet/blocked-address-refund

POST /v1/balance

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

третий способ принять оплату, без бэкенда.

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

инвойс.