Merchant API

Общие положения

Merchant API позволяет backend продавца работать с Weelay программно: проверить текущий API-ключ, создать счёт, получить список счетов и получить один счёт.

Base URL:

https://api.weelay.com/v1

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

Авторизация

Merchant API использует secret API key проекта.

Каждый защищённый запрос должен содержать header:

Authorization: Bearer weelay_secret_...

Secret key должен начинаться с weelay_secret_.

Если header отсутствует, ключ неверный, ключ отозван, проект неактивен или аккаунт неактивен, API вернёт ошибку.

Рекомендуемые headers

Для JSON-запросов используйте:

• Accept: application/json;
• Content-Type: application/json;
• Authorization: Bearer weelay_secret_....

Health endpoint

GET /health

Полный URL:

https://api.weelay.com/v1/health

Этот endpoint проверяет, что API отвечает. Merchant secret key для него не нужен.

Проверка API-ключа

GET /merchant/me

Полный URL:

https://api.weelay.com/v1/merchant/me

Endpoint возвращает данные текущего проекта и API-ключа.

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

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

POST /merchant/invoices

Полный URL:

https://api.weelay.com/v1/merchant/invoices

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

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

Поля запроса:

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

amount должен передаваться строкой, а не числом.

Idempotency-Key

При создании счёта рекомендуется передавать header:

Idempotency-Key: order-1001

Если backend продавца повторит запрос с тем же Idempotency-Key, Weelay вернёт уже созданный счёт вместо создания дубля.

Это защищает продавца от повторного создания счёта при timeout, сетевой ошибке или повторной отправке запроса.

Ответ при создании счёта

При успешном создании счёта API возвращает статус 201.

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

• id — публичный id счёта;
• project_id — публичный id проекта;
• status — статус счёта;
• amount — сумма к оплате;
• currency — валюта;
• network — сеть оплаты;
• order_id — id заказа продавца, если был передан;
• payment_url — ссылка на страницу оплаты;
• payment_expires_at — срок оплаты;
• paid_at — время оплаты, если счёт оплачен;
• tx_hash — hash транзакции, если платёж найден;
• created_at;
• updated_at.

Сохраняйте id, order_id, payment_url и status у себя в системе.

Список счетов

GET /merchant/invoices

Полный URL:

https://api.weelay.com/v1/merchant/invoices

Query parameters:

• status — необязательный фильтр по статусу;
• limit — количество записей от 1 до 100;
• page — номер страницы.

Пример query:

GET /merchant/invoices?status=pending&limit=20&page=1

Ответ содержит список счетов и данные pagination.

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

GET /merchant/invoices/{invoice}

Полный URL:

https://api.weelay.com/v1/merchant/invoices/{invoice}

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

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

Статусы счетов

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

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

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

Формат успешного ответа

Успешный ответ содержит:

• success;
• message;
• data;
• meta, если есть дополнительные данные;
• trace_id.

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

Формат ошибки

Ошибка содержит:

• success;
• message;
• error.code;
• error.details;
• trace_id.

Сохраняйте trace_id в своих логах, но не логируйте полный secret API key.

Основные ошибки

Возможные ошибки авторизации:

• API_KEY_REQUIRED;
• API_KEY_INVALID_FORMAT;
• API_KEY_INVALID;
• API_KEY_REVOKED;
• PROJECT_NOT_ACTIVE;
• ACCOUNT_NOT_ACTIVE.

Возможные общие ошибки:

• VALIDATION_ERROR;
• NOT_FOUND;
• METHOD_NOT_ALLOWED;
• RATE_LIMITED;
• INTERNAL_SERVER_ERROR.

Лимиты запросов

Merchant API использует лимиты запросов.

Если лимит превышен, API вернёт ошибку RATE_LIMITED со статусом 429.

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

Безопасность secret key

Secret API key должен храниться только на backend.

Нельзя:

• отправлять secret key в браузер;
• вставлять secret key во frontend JavaScript;
• хранить secret key в открытом репозитории;
• писать полный secret key в логи;
• отправлять secret key в чаты, тикеты или скриншоты.

Если ключ раскрыт, отзовите его в dashboard и создайте новый.

Production-рекомендации

Для production-интеграции:

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

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

После этой страницы полезно прочитать:

• Руководство подключения;
• Счета;
• Статусы счетов;
• Idempotency-Key;
• Webhook-уведомления;
• Ошибки API.