Быстрый старт

Шаг 1. Регистрация и создание проекта

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

В v1 кабинета на сайте ещё нет. Регистрация ведёт в продукт, там вы управляете проектами и ключами.

Шаг 2. Создайте API-ключ

Внутри проекта создайте API-ключ v2. Вы передаёте его в заголовке X-Api-Key на каждом server-to-server вызове. У ключей свой rate-limit, их можно ротировать, а отзываете ключ по его префиксу.

Suward аутентифицирует двумя способами: cookie-сессия (HttpOnly accessToken и refreshToken) для браузерного дашборда и заголовок X-Api-Key для серверной интеграции. Держите ключ на бэкенде и никогда не отдавайте его в браузер.

Шаг 3. Создайте платёж

Один платёж — это один актив на одной сети. Передайте сумму, актив, опциональный externalId (ссылку на ваш заказ) и callbackUrl. В ответ придёт уникальный депозитный адрес только для этого платежа.

Передавайте свой externalId как ключ заказа. Отправьте тот же externalId ещё раз — и Suward вернёт существующий платёж, не откроет второй. Денежные значения — строки, не float. Один платёж ограничен суммой 60 000.

1curl -X POST https://api.suward.com/v1/projects/{projectId}/payments \
2  -H "X-Api-Key: <API_KEY>" \
3  -H "Content-Type: application/json" \
4  -d '{"amount":"100.00","asset":"USDT","externalId":"order-42","isTest":false}'

Шаг 4. Покажите checkout

Два способа собрать платёж. Перенаправьте покупателя на готовую страницу Suward с QR-адресом, индикатором watching mempool и обратным отсчётом. Или соберите свой UI из address, amount и asset и следите за статусом сами.

Встраиваемого виджета или JS SDK пока нет, только hosted-редирект. URL hosted checkout приходит в ответе на создание платежа.

Шаг 5. Проверьте статус платежа

Опрашивайте платёж, пока он не дойдёт до терминального статуса. Статус приходит двумя уровнями: status (верхний: PENDING, ACCEPTED, SUCCESS, FAILED) и subStatus (on-chain: Pending → Safe → Finalized). Публичный GET /v1/payments/{paymentId} подходит для checkout-страницы, путь в рамках проекта возвращает полную картину.

Читайте имена статусов динамически из GET /v1/paymentStatuses, а не хардкодьте их, чтобы интеграция пережила будущее изменение статусов.

1# Public endpoint — no auth needed for the checkout page
2curl https://api.suward.com/v1/payments/{paymentId}

Шаг 6. Прочитайте баланс

После того как платёж достигает SUCCESS, сумма зачисляется в баланс проекта. Балансы делятся на safe и accepted, хранятся как Decimal128 и никогда не уходят в минус.

1curl https://api.suward.com/v1/projects/{projectId}/balances \
2  -H "X-Api-Key: <API_KEY>"