Syncra Merchant API V2 — полная документация для интеграции

Merchant API V2

Добро пожаловать в документацию Syncra Merchant API V2. Этот программный интерфейс разработан для мерчантов (онлайн-сервисы, платформы, ритейлеры), которым требуется надёжный и масштабируемый процессинг P2P-платежей в реальном времени.

С помощью нашего API вы можете полностью автоматизировать прием платежей (PayIn), отправку выплат (PayOut), управление балансами мерчанта, отслеживание диспутов и интеграцию с криптографическими кошельками (USDT) для вывода средств.

Базовая информация

Базовый URL

Все запросы к Merchant API V2 должны отправляться на следующий базовый адрес:

https://api.syncra.money/api/v1/p2p/merchant

Обратите внимание, что устаревшая legacy-версия API (V1) доступна по адресу https://api.syncra.money/v1/ только для совместимости ранее интегрированных мерчантов. Новым клиентам настоятельно рекомендуется сразу использовать эндпоинты V2 по основному пути.

Формат данных

Интерфейс спроектирован по принципу REST с использованием JSON в качестве основного формата передачи данных:

Запросы должны содержать заголовок Content-Type: application/json.
Все тела ответов возвращаются в формате JSON.
Имена полей в телах запросов и ответов отформатированы с использованием snake_case.
Для всех временных меток используется стандарт ISO 8601 (например, 2026-07-12T15:00:00Z).

Лимиты и Rate Limiting

Для защиты платформы от перегрузок и DDoS-атак применяется интеллектуальное ограничение частоты запросов (Rate Limiting). Лимиты настраиваются индивидуально для каждого мерчанта на уровне системы:

По умолчанию: 300 запросов в минуту на один токен мерчанта.
При превышении лимита сервер возвращает стандартный HTTP-статус 429 Too Many Requests.

Ответ с кодом 429 содержит JSON-структуру с описанием ошибки:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

Обзор эндпоинтов

Ниже представлена сводная таблица основных доступных API-методов V2:

Категория	Метод	Эндпоинт	Описание
PayIn	POST	`/deals/payin`	Создание заявки на прием платежа (пополнение)
PayOut	POST	`/deals/payout`	Создание заявки на выплату клиенту
Deals	GET	`/deals/{deal_id}`	Получение информации о конкретной сделке (PayIn/PayOut)
Deals	GET	`/deals`	Список и история сделок мерчанта с фильтрами и пагинацией
Balances	GET	`/balance`	Запрос доступных балансов мерчанта по валютам (мультивалютный ответ)
Withdraw	POST	`/wallet/withdraw`	Заявка на криптографический вывод средств (USDT)
Appeals	POST	`/appeals`	Создание апелляции (спора) по сделке
Appeals	GET	`/appeals/{appeal_id}`	Информация о конкретной апелляции
Appeals	GET	`/appeals`	Список апелляций мерчанта
Appeals	POST	`/appeals/{appeal_id}/messages`	Отправка сообщения в чат апелляции
Appeals	GET	`/appeals/{appeal_id}/messages`	Получение истории сообщений чата апелляции
Banks	GET	`/banks`	Получение списка доступных банков и методов оплаты

Быстрый старт (Quick Start)

Чтобы выполнить первый тестовый запрос на получение баланса вашего мерчанта, воспользуйтесь утилитой curl. Вам понадобятся ваши API-ключи, полученные в панели управления:

curl -X GET https://api.syncra.money/api/v1/p2p/merchant/balance \
  -H "X-Merchant-Token: your_merchant_token_here" \
  -H "X-Timestamp: 1783856120" \
  -H "X-Signature: t=1783856120,v1=9e87d0c3c8801d0a5198d023b6b19a16f2c8d2037920ab3e09819cd8e412cfab" \
  -H "Content-Type: application/json"

В ответ вы получите актуальное состояние балансов мерчанта:

{
  "data": [
    {
      "currency": "RUB",
      "available": 15000000,
      "frozen": 0
    },
    {
      "currency": "USDT",
      "available": 500000,
      "frozen": 12000
    }
  ]
}

Подробную информацию о том, как правильно рассчитать заголовок подписи X-Signature и защитить ваши интеграции от атак повторного воспроизведения, вы найдете в разделе Аутентификация.

Syncra Merchant API V2