Счета

Что такое счёт

Счёт, или invoice, — это основная платёжная сущность Weelay.

Счёт связывает заказ продавца с оплатой покупателя в USDT TRC20.

Через счёт продавец получает payment_url, покупатель открывает страницу оплаты, а Weelay возвращает продавцу статус оплаты.

Счёт не является балансом Weelay. Средства отправляются напрямую на wallet address продавца.

Когда создаётся счёт

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

Backend продавца отправляет запрос POST /merchant/invoices, получает данные счёта и перенаправляет покупателя на payment_url.

Минимальные данные для создания

Для создания счёта нужно передать amount.

amount — обязательная строка с положительной суммой.

Пример: 10.55.

Также можно передать order_id.

order_id — это внутренний номер заказа продавца. Он помогает связать счёт Weelay с заказом в системе продавца.

Почему amount должен быть строкой

Деньги нельзя безопасно передавать как float.

Поэтому amount передаётся строкой, например 10.55, а не числом.

Так меньше риск ошибок округления между разными системами.

Основные поля счёта

Ответ API по счёту содержит публичные поля, которые нужны продавцу для интеграции.

Основные поля:

• id;
• project_id;
• status;
• amount;
• currency;
• network;
• order_id;
• payment_url;
• payment_expires_at;
• paid_at;
• tx_hash;
• created_at;
• updated_at.

id

id — публичный идентификатор счёта.

Он имеет формат inv_....

Используйте этот id для получения счёта через API, поддержки покупателя и связи с webhook-событиями.

status

status показывает текущее состояние счёта.

Основные статусы:

• pending — счёт создан и ждёт оплату;
• paid — оплата найдена и подтверждена;
• expired — срок оплаты истёк;
• failed — счёт не может быть успешно завершён.

Заказ продавца должен выполняться только после статуса paid.

amount

amount показывает сумму счёта.

При создании счёта продавец передаёт сумму строкой.

Покупатель должен отправить сумму, указанную на странице оплаты.

currency и network

Weelay поддерживает оплату в USDT TRC20.

В ответе API:

• currency — валюта счёта;
• network — сеть оплаты.

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

Платёж в другой сети может не быть найден автоматически.

order_id

order_id — внутренний номер заказа продавца.

Weelay не создаёт order_id за продавца.

Рекомендуется передавать order_id, чтобы потом быстро найти заказ у себя в системе.

payment_url

payment_url — ссылка на страницу оплаты Weelay.

После создания счёта продавец должен показать эту ссылку покупателю или перенаправить покупателя на неё.

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

payment_expires_at

payment_expires_at показывает срок действия счёта.

Покупатель должен оплатить счёт до этого времени.

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

paid_at

paid_at показывает время, когда счёт был отмечен как оплаченный.

Если счёт ещё не оплачен, поле пустое.

tx_hash

tx_hash — hash blockchain-транзакции, если оплата найдена и связана со счётом.

Это поле полезно для сверки оплаты, поддержки покупателя и разбора спорных ситуаций.

created_at и updated_at

created_at показывает время создания счёта.

updated_at показывает время последнего обновления счёта.

Даты возвращаются в ISO 8601 формате.

Создание счёта

Счёт создаётся через POST /merchant/invoices.

Минимальный body:

{"amount":"10.55","order_id":"ORDER-1001"}

order_id необязателен, но рекомендуется.

Для защиты от дублей используйте Idempotency-Key.

Получение списка счетов

Список счетов можно получить через GET /merchant/invoices.

Доступные query parameters:

• status;
• limit;
• page.

Это удобно для панели продавца, поддержки, сверки и ручной проверки заказов.

Получение одного счёта

Один счёт можно получить через GET /merchant/invoices/{invoice}.

{invoice} должен быть публичным id формата inv_....

Продавец может получить только счёт своего проекта.

Когда выполнять заказ

Заказ считается оплаченным только после статуса paid.

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

pending означает, что оплата ещё не подтверждена.

Спорные ситуации

В спорной ситуации проверьте:

• id;
• order_id;
• status;
• amount;
• payment_url;
• payment_expires_at;
• paid_at;
• tx_hash.

Если покупатель утверждает, что оплатил, попросите его прислать tx_hash.

Итог

Счёт Weelay связывает заказ продавца с оплатой покупателя в USDT TRC20.

Главные поля для интеграции: id, order_id, status, amount, payment_url, payment_expires_at, paid_at и tx_hash.

Заказ выполняется только после статуса paid.