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

Smerch Integration API — это сервер-сервер API для приёма платежей, балансов, выводов и возвратов.

Базовый путь: /api/v1/...

Интеграционные методы: /api/v1/integration/...

Аутентификация: X-Api-Key + HMAC

Источник статуса платежа/вывода: webhook, а не бесконечный polling

Не входит в этот пакет документации:

admin / platform API

JWT и MFA личного кабинета

входящие webhook'и платёжных провайдеров (Platega и т.п.)

Что обычно делают мерчанты

Получают API key и secret в кабинете.

Настраивают URL для webhook и сохраняют webhook secret.

Создают платёж (POST /integration/transactions).

Отправляют плательщика по ссылке / показывают реквизиты H2H.

Ждут webhook со статусом и обновляют свой заказ.

При необходимости делают вывод или возврат.

Суммы — целые минорные единицы (для RUB — копейки: 10000 = 100,00 ₽).

Не отправляйте float (100.5) — только integer.

Для crypto-единиц смотрите схему в OpenAPI: там указана точность.

Что	Кто задаёт	Зачем
`external_id`	вы	ваш id заказа; удобно для безопасных повторов и поиска
`uuid`	Smerch	наш id транзакции / выплаты / возврата
`Idempotency-Key`	вы	обязателен для возвратов (и части v2 create)

Один и тот же Idempotency-Key + то же тело = безопасный повтор.
Тот же ключ + другое тело = конфликт.

v1 — основная поверхность для интеграций сегодня.

v2 — более строгий HMAC и формат ошибок (Problem Details); пока не полная замена v1.

Для новой интеграции ориентируйтесь на HMAC v2 даже на /api/v1, если платформа требует v2 для вашего аккаунта.