Smerch — API интеграции для мерчантов
    • Быстрый старт
    • Возвраты
    • Песочница, ошибки и go-live
    • Вебхуки (исходящие колбэки)
    • Авторизация и HMAC
    • Балансы и курсы
    • Платежи
    • Выводы (выплаты)
    • Авторизация
      • Проверить, что API отвечает
        GET
    • Балансы
      • Посмотреть балансы
        GET
    • Выводы
      • Создать вывод средств
        POST
      • Посчитать вывод без списания
        GET
      • Получить вывод по UUID
        GET
    • Возвраты
      • Сделать возврат по платежу
        POST
    • Песочница
      • Песочница: симулировать отказ оплаты
        POST
      • Песочница: отказ, затем запоздавшая оплата
        POST
      • Песочница: симулировать успешную оплату
        POST
      • Песочница: симулировать истечение платежа
        POST
    • Платежи
      • Список платежей
        GET
      • Создать платёж
        POST
      • Найти платёж по вашему external_id
        GET
      • Получить платёж по UUID
        GET
    • Вебхуки
      • Посмотреть настройки webhook
        GET
      • Задать URL для колбэков
        PUT
      • Журнал доставок webhook
        GET
      • Сменить secret подписи webhook
        POST
      • Отправить тестовый колбэк
        POST
      • Событие: изменился статус платежа
      • Событие: изменился статус вывода
    • Balances
      • Service method
    • Payments
      • Service method
    • Schemas
      • CreatePayoutRequest
      • CreateRefundRequest
      • CreateTransactionRequest
      • CursorMeta
      • ErrorResponse
      • HealthResponse
      • IntegrationBalancesResponse
      • MerchantBalance
      • MerchantPayoutCallback
      • MerchantTransactionCallback
      • PayoutQuoteResponse
      • PayoutResponse
      • RatesResponse
      • RefundResponse
      • StructuredError
      • TransactionResponse
      • TransactionCursorPage
      • ValidationErrorResponse

    Песочница, ошибки и go-live

    Песочница#

    Маршруты /api/v1/integration/sandbox/transactions/{transaction}/... симулируют колбэки провайдера:
    ДействиеСмысл
    payуспешная оплата
    failотказ
    timeoutистечение / expired
    out-of-orderсначала fail, потом запоздавший paid
    Доступны только для non-production / тестовых ключей. В live на них полагаться нельзя.

    Ошибки#

    Типичные HTTP-коды:
    КодСмысл
    401не прошла аутентификация / HMAC
    403ключ ок, но действие запрещено (IP allowlist, disabled merchant, …)
    404сущность не найдена
    409конфликт идемпотентности
    422ошибка валидации полей
    429rate limit
    В v2 ошибки ближе к Problem Details (RFC 9457). В v1 чаще JSON с message / errors.

    Чеклист перед боем#

    1.
    HMAC v2 на всех Integration-запросах.
    2.
    Secret'ы только на сервере.
    3.
    Webhook URL на HTTPS, проверка подписи включена.
    4.
    Обработка webhook идемпотентна.
    5.
    Суммы в минорных единицах.
    6.
    Для возвратов всегда Idempotency-Key.
    7.
    Sandbox прогнан: pay / fail / timeout.
    8.
    IP allowlist (если включён) содержит ваши egress IP.
    Modified at 2026-07-23 06:43:53
    Previous
    Возвраты
    Next
    Вебхуки (исходящие колбэки)
    Built with