Merchant API V2

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

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

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

Базовый URL

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

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

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

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

• Запросы должны содержать заголовок Content-Type: application/json.
• Все тела ответов возвращаются в формате JSON (кроме CSV-экспорта с Accept: text/csv).
• Имена полей — snake_case.
• Временные метки — ISO 8601 (например, 2026-07-12T15:00:00Z).
• Денежные суммы — int64 в минорных единицах (копейки/центы/satoshi); в JSON-ответах API значения int64 передаются строками ("amount": "100000" — канон proto3 JSON, исключает потерю точности в JS-клиентах). В телах вебхуков суммы — обычные числа ("amount": 250050).
• Успешные ответы — канон-конверт по типу ответа: единичный объект — напрямую ({"deal": {...}}); все списки/листинги (GET /deals, GET /callbacks, GET /payment-methods, GET /appeals, /passes, /banks, /currencies, /wallet/deposits, /wallet/withdrawals, /deals/turnover) — единый конверт {"data": [...], "next_page_token": ""} (AIP-158: пустая строка = последняя страница; других полей конверт не несёт — total_count на HTTP не отдаётся). Исключение — GET /balance ({"wallets": [...]}): он не листинг, а проекция баланса.
• Все ошибки (non-2xx) — RFC 9457 application/problem+json (см. Коды ошибок): type/title/status/detail (с вложенными gRPC-деталями)/instance; трассировка — заголовком X-Trace-Id. Неверное состояние запроса (нехватка баланса, дневной лимит, повторная апелляция) → 400 (не 409).

Лимиты и Rate Limiting

Для защиты платформы применяется ограничение частоты запросов (Rate Limiting), настраиваемое per-merchant:

• По умолчанию: 10 000 запросов в минуту на один токен мерчанта (per-merchant rate_limit_per_minute; окно — календарная минута UTC).

• Каждый ответ несёт заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix-секунды сброса окна).

• При превышении — HTTP 429 Too Many Requests с телом RFC 9457 problem+json (см. Коды ошибок):

  {
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "{\"code\":8,\"message\":\"merchant rate limit exceeded (limit: 10000/min)\",\"details\":[]}",
    "instance": "/api/v1/p2p-engine"
  }

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

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

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

Первый тестовый запрос — получение баланса мерчанта:

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"

Ответ (RetrieveMerchantBalanceResponse) — массив wallets[] верхнего уровня (без обёртки data), каждый элемент — реальный кошелёк мерчанта из money-сервиса со своей валютой и wallet_id: wallet_id, currency, available, frozen, total (все суммы — int64 в минорных единицах, в JSON передаются строками). Живой ответ стейджа:

{
  "wallets": [
    {
      "wallet_id": "1af2d1ee-7fc3-4796-9dda-10d97af62094",
      "currency": "USDT",
      "available": "95982",
      "frozen": "4018",
      "total": "100000"
    },
    {
      "wallet_id": "9b2fcbd6-b6f4-4f17-a94d-b7309f84bde5",
      "currency": "USDT",
      "available": "0",
      "frozen": "0",
      "total": "0"
    }
  ]
}