Руководство по миграции (V1 → V2)

Это руководство предназначено для технических специалистов мерчантов, уже интегрированных с устаревшей P2P-платформой V1 (базирующейся на C#/.NET шлюзе api-merchant.syncra.me). В нем описан детальный процесс перевода вашей системы на новое API V2 (api.syncra.money).

Для обеспечения бесшовного переключения в Syncra V2 встроен Compatibility Adapter (Адаптер совместимости), который позволяет вашему старому коду работать без изменений в течение переходного периода (6 месяцев). Однако для использования преимуществ повышенной производительности, лимитов и безопасности мы рекомендуем выполнить полноценную миграцию.

Чеклист миграции из 10 шагов

1. Получить учетные данные V2: Войдите в новый личный кабинет администратора и сгенерируйте API-токен V2 и Webhook Secret.
2. Изменить базовый URL: Обновите адрес отправки запросов с https://api-merchant.syncra.me/v1/ на https://api.syncra.money/api/v1/p2p/merchant/.
3. Обновить заголовки аутентификации:
   • Замените заголовок MERCHANT на X-Merchant-Token.
   • Замените заголовок SIGNATURE на X-Signature.
   • Добавьте обязательный заголовок X-Timestamp.
4. Заменить алгоритм подписи: Смените HMAC-SHA512 на HMAC-SHA256.
5. Изменить формат полезной нагрузки подписи: Вместо склеивания полей через точку с запятой (ts;id;salt) перейдите на стандартную формулу подписи тела запроса: timestamp + "." + raw_body.
6. Обновить формат суммы (Amount): Переведите суммы со строкового представления с точкой (например, "1500.50") на целочисленные копейки (например, 150050 в int64).
7. Обновить коды валют: Замените целочисленные коды ISO на трехбуквенные строковые коды (например, 643 → "RUB", 10001 → "USDT").
8. Обновить обработку ответов: Перейдите со старого конверта ответа {failures, value, isSuccess} на структуру {data: { ... }}.
9. Обновить проверку подписей вебхуков: Перенастройте ваш обработчик вебхуков на декодирование нового формата подписи X-Syncra-Signature на основе алгоритма SHA256 (вместо привязки к началу суток StartOfDay в V1).
10. Провести тестирование: Проверьте весь платежный флоу на тестовом окружении (staging) и переключите боевой трафик.

Таблица маппинга параметров (PayIn Request)

При переходе с V1 на V2 параметры запроса пополнения изменяются следующим образом:

Таблица маппинга параметров (PayOut Request)

При переходе с V1 на V2 параметры запроса выплаты изменяются следующим образом:

Сравнение примеров кода (PHP)

Как было в API V1 (HMAC-SHA512 + ";" separator)

<?php
// API V1
$merchantGuid = "7ac148fe-19a3-45bb-b992-019fac55b721";
$merchantSecret = "legacy_secret_key";
$timestamp = time();
$payInId = "order_12345";
$salt = "random_salt_99";

$payload = "{$timestamp};{$payInId};{$salt}";
$signature = hash_hmac('sha512', $payload, $merchantSecret);

$headers = [
    "MERCHANT: {$merchantGuid}",
    "SIGNATURE: {$signature}",
    "Content-Type: application/json"
];

$body = json_encode([
    "payInId" => $payInId,
    "amount" => "1500.50",
    "currency" => 643,
    "salt" => $salt
]);
// Отправка на https://api-merchant.syncra.me/v1/payments/incoming
?>

Как стало в API V2 (HMAC-SHA256 + body signature)

<?php
// API V2
$merchantToken = "a1b2c3d4e5f607182930a4b5c6d7e8f901a2b3c4d5e6f7081920a3b4c5d6e7f8";
$webhookSecret = "whsec_920ab3e09819cd8e412cfab9e87d0c3c";
$timestamp = time();

$body = json_encode([
    "amount" => 150050, // в копейках
    "currency" => "RUB",
    "idempotency_key" => "order_12345"
]);

$payload = $timestamp . '.' . $body;
$signature = hash_hmac('sha256', $payload, $webhookSecret);

$headers = [
    "X-Merchant-Token: {$merchantToken}",
    "X-Timestamp: {$timestamp}",
    "X-Signature: t={$timestamp},v1={$signature}",
    "Content-Type: application/json"
];
// Отправка на https://api.syncra.money/api/v1/p2p/merchant/deals/payin
?>

Важные подводные камни (Gotchas & Edge Cases)

1. Конвертация сумм (Amount): При преобразовании сумм из строкового формата V1 в int64 V2 строго запрещено использовать типы с плавающей точкой (float, double). Используйте строковый парсинг: разделите строку по символу точки ., проверьте, что количество знаков в дробной части не превышает двух, дополните нулями при необходимости и преобразуйте в целое число копеек. Например, "1500.5" -> "1500" и "5" -> "1500" и "50" -> 150050.

2. Подписи вебхуков: Старые вебхуки V1 подписывались на основе времени начала суток в формате UTC (StartOfDay). Новые вебхуки V2 используют текущее реальное время отправки вебхука (Timestamp). Не забудьте обновить логику валидации на вашем принимающем скрипте.

3. Статусы выплаты (PayOut): В отличие от входящих платежей, выплата (PayOut) не имеет отдельного статуса EXPIRED (Таймаут). Любая отклоненная или зависшая выплата сразу переходит в финальный ошибочный статус Failed (код 30 в V1 / CANCELLED в V2).