Smerch Integration API — это сервер-сервер API для приёма платежей, балансов, выводов и возвратов.Базовый путь: /api/v1/...
Интеграционные методы: /api/v1/integration/...
Аутентификация: X-Api-Key + HMAC (см. «Авторизация и HMAC»)
Источник статуса платежа/вывода: webhook, а не бесконечный polling
JWT и MFA личного кабинета
входящие webhook'и платёжных провайдеров
Что обычно делают мерчанты#
1.
Создают API-ключ в кабинете (он же используется для HMAC-подписи).
2.
Настраивают URL для webhook и сохраняют webhook secret.
3.
Создают платёж (POST /integration/transactions).
4.
Отп равляют плательщика по ссылке оплаты.
5.
Ждут webhook со статусом и обновляют свой заказ.
6.
При необходимости делают вывод или возврат.
Деньги#
Суммы — целые минорные единицы (RUB/USD: копейки/центы, 10000 = 100,00).
Для рублёвых методов, включая СБП, передавайте currency=RUB; amount указывается в копейках.
payment_method=crypto — отдельный сценарий: плательщик оплачивает поддерживаемым криптоактивом в выбранной сети. Используйте данные оплаты из ответа API.
Не отправляйте float (100.5) — только integer.
Для crypto-единиц смотрите схему в OpenAPI: там указана точность.
Идентификаторы#
| Что | Кто задаёт | Зачем |
|---|
external_id | вы | ваш id заказа; удобно для безопасных повторов и поиска |
uuid | Smerch | наш id транзакции / выплаты / возврата |
Idempotency-Key | вы | обязателен для возвратов (и части v2 create) |
Один и тот же Idempotency-Key + то же тело = безопасный повтор.
Тот же ключ + другое тело = конфликт.Версии API#
v1 — основная поверхность для интеграций сегодня.
v2 — ошибки в формате Problem Details; пока не полная замена v1.
/api/v1 и /api/v2 — см. «Авторизация и HMAC».Дальше#
1.
«Авторизация и HMAC» — подпись запросов
3.
«Вебхуки (исходящие колбэки)» — колбэки
Modified at 2026-10-20 12:24:47
