Руководство подключения

Общая схема

Это руководство показывает базовый порядок подключения Weelay к сайту или backend продавца.

Weelay работает как некастодиальный checkout для USDT TRC20: продавец создаёт счёт, покупатель оплачивает его на странице Weelay, а backend продавца получает статус оплаты через API или webhook.

Secret API key должен храниться только на backend. Нельзя размещать его во frontend, публичном JavaScript, мобильном приложении без защищённого backend или открытом репозитории.

Что нужно до начала

Перед подключением нужно подготовить аккаунт Weelay, подтверждённый email, проект в dashboard, USDT TRC20 wallet address продавца, secret API key проекта и webhook endpoint, если нужна автоматическая доставка событий.

Шаг 1. Создайте аккаунт

Зарегистрируйтесь в Weelay и подтвердите email.

После входа в dashboard можно создавать проекты, API-ключи, счета и настраивать webhook.

Шаг 2. Создайте проект

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

В проекте обычно задаются название, USDT TRC20 wallet address, webhook URL и статус проекта.

Проект должен быть активным, чтобы secret API key мог использоваться для Merchant API.

Шаг 3. Укажите USDT TRC20 wallet address

Wallet address — это адрес продавца, на который покупатели будут отправлять оплату.

Проверьте адрес внимательно.

Weelay не хранит средства, не управляет кошельком и не может вернуть платёж, если адрес указан неверно.

Шаг 4. Создайте secret API key

В dashboard проекта создайте secret API key.

Secret key имеет формат weelay_secret_....

Полное значение secret key показывается только один раз при создании. Сохраните его в защищённом месте на backend.

Шаг 5. Настройте backend-переменные

На стороне backend продавца удобно хранить настройки в переменных окружения.

Используйте base URL https://api.weelay.com/v1.

Secret key храните в закрытой backend-переменной, например WEELAY_SECRET_KEY.

Не храните secret key во frontend-коде.

Шаг 6. Проверьте API-ключ

Для проверки подключения backend может вызвать GET /merchant/me.

Запрос должен идти на https://api.weelay.com/v1/merchant/me.

В запросе должен быть header Authorization: Bearer weelay_secret_....

Если ключ активен, проект активен и пользователь не заблокирован, API вернёт данные текущего merchant context.

Шаг 7. Создайте счёт

Для создания счёта backend продавца отправляет POST /merchant/invoices.

Запрос должен идти на https://api.weelay.com/v1/merchant/invoices.

Минимальные поля:

• amount — сумма строкой, например 10.55;
• order_id — внутренний номер заказа продавца, необязательное поле.

Для production-интеграции рекомендуется передавать header Idempotency-Key, чтобы повторный запрос не создал дубль счёта.

Шаг 8. Сохраните ответ Weelay

После создания счёта backend продавца должен сохранить у себя основные поля ответа:

• id;
• status;
• amount;
• currency;
• order_id;
• payment_url;
• payment_expires_at;
• tx_hash, если он появится позже.

Главное поле для перенаправления покупателя — payment_url.

Шаг 9. Перенаправьте покупателя на оплату

После создания заказа и счёта продавец перенаправляет покупателя на payment_url.

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

Покупатель отправляет USDT TRC20 напрямую на адрес продавца.

Шаг 10. Дождитесь статуса paid

После создания счёт получает статус pending.

Пока статус pending, заказ нельзя считать оплаченным.

После успешной проверки оплаты счёт получает статус paid.

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

Шаг 11. Получайте статус счёта через API

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

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

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

Шаг 12. Настройте webhook

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

Текущий основной event — invoice.paid.

Когда счёт оплачен, Weelay создаёт webhook delivery и отправляет POST запрос на webhook URL проекта.

Backend продавца должен принять webhook, проверить подпись, найти заказ по order_id или invoice id, убедиться, что событие ещё не обработано, обновить заказ как оплаченный и быстро вернуть успешный HTTP-ответ.

Шаг 13. Обрабатывайте webhook идемпотентно

Webhook может прийти повторно. Это нормально для надёжной доставки.

Backend продавца не должен повторно выдавать товар, услугу или доступ, если событие invoice.paid уже было обработано ранее.

Используйте invoice id, tx_hash или собственный order_id для защиты от повторной обработки.

Шаг 14. Обрабатывайте ошибки API

API может вернуть ошибку, если secret key отсутствует, secret key неверный, проект неактивен, данные запроса не прошли проверку, превышены лимиты, счёт не найден или произошла внутренняя ошибка.

Сохраняйте trace_id из ответа. Он нужен для диагностики и обращения в поддержку.

Шаг 15. Проверьте полный сценарий

Перед реальным использованием проверьте полный путь:

1. Создайте заказ в своей системе.
2. Создайте счёт через Weelay API.
3. Откройте payment_url.
4. Проверьте сумму, сеть и адрес.
5. Выполните тестовую оплату.
6. Дождитесь статуса paid.
7. Проверьте webhook delivery.
8. Убедитесь, что заказ обновился один раз.
9. Проверьте, что повтор webhook не ломает заказ.
10. Проверьте ошибку с неправильным API key.

Минимальный production-чеклист

Перед запуском убедитесь, что secret API key хранится только на backend, amount передаётся строкой, order_id сохраняется у продавца, Idempotency-Key используется при создании счёта, payment_url сохраняется в заказе, заказ выполняется только после paid, webhook signature проверяется, webhook обрабатывается идемпотентно, ошибки API логируются без secret key, а trace_id сохраняется для диагностики.

Куда идти дальше

После этого руководства полезно прочитать Merchant API, Счета, Статусы счетов, Idempotency-Key, Webhook-уведомления, Ошибки API и Некастодиальное уведомление.