Прием платежей (PayIn)

Функционал входящих платежей (PayIn) позволяет мерчантам автоматизировать приём средств от физических лиц через СБП, банковские карты (Card2Card), международные переводы по IBAN и другие методы онлайн-оплаты. Платформа не привязана к конкретной стране: доступные рынки (РФ, СНГ, Турция, ЕС, ...) определяются конфигурацией вашего тенанта, а выбор канала под капотом payment_method_id — типом реквизита (RequisiteType). Полный справочник типов — в разделе Типы реквизитов.

Процесс оплаты (PayIn Flow)

1. Создание сделки. Мерчант отправляет POST /deals/payin, указывая amount, currency, idempotency_key и payment_method_id (UUID или слаг метода из каталога).
2. Получение URL оплаты. В ответе — deal_id (UUID сделки) и payment_url (hosted payform).
3. Перевод средств. Клиент переходит по payment_url, видит реквизиты P2P-трейдера и совершает перевод в мобильном банке.
4. Уведомление. После верификации поступления шлюз шлёт мерчанту webhook deal.completed (см. Callbacks).

Эндпоинт создания PayIn

POST /api/v1/p2p/merchant/deals/payin

Параметры запроса (JSON Body)

Пример запроса

{
  "amount": 250050,
  "currency": "RUB",
  "idempotency_key": "order_uuid_abc123456",
  "client_id": "player_user_9921",
  "payment_method_id": "550e8400-e29b-41d4-a716-446655440000",
  "currency_id": "9a3f1c2e-1234-4abc-9def-56789abcdef0",
  "payer_bank": "sber",
  "description": "Пополнение счёта игрока player_user_9921",
  "callback_url": "https://merchant.example/callbacks/syncra",
  "is_client_commission": false
}

Пример ответа (200 OK)

Ответ — объект MerchantDealInfo в поле deal верхнего уровня (обёртки data нет). Ключевое поле идентификатора — deal_id (НЕ id). URL платёжной страницы — payment_url (НЕ payment_page_url).

{
  "deal": {
    "deal_id": "7ac148fe-19a3-45bb-b992-019fac55b721",
    "status": "ESCROW_LOCKED",
    "amount": "250050",
    "currency": "RUB",
    "created_at": "2026-07-12T17:20:00Z",
    "client_id": "player_user_9921",
    "deal_type": "PAYIN",
    "updated_at": "2026-07-12T17:20:00Z",
    "payment_url": "https://checkout.syncra.money/pay/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "target_requisite": "",
    "received_amount": "0",
    "amount_match_status": ""
  }
}

Пример ответа для TRY (BANK_TRANSFER / Havale)

Создание PayIn в TRY ничем не отличается от RUB: тот же эндпоинт, тот же набор полей — меняются currency и payment_method_id (UUID IBAN-метода из GET /payment-methods).

{
  "deal": {
    "deal_id": "9d4a07c2-3b1e-4f6a-9c25-8e7f1b0d3a44",
    "status": "ESCROW_LOCKED",
    "amount": "2500000",
    "currency": "TRY",
    "created_at": "2026-08-18T10:05:00Z",
    "client_id": "player_user_4477",
    "deal_type": "PAYIN",
    "updated_at": "2026-08-18T10:05:00Z",
    "payment_url": "https://checkout.syncra.money/pay/f3e2d1c0b9a80796f5e4d3c2b1a0f9e8d7c6b5a49382716055f4e3d2c1b0a9988",
    "target_requisite": "",
    "received_amount": "0",
    "amount_match_status": ""
  }
}

amount: 2500000 = 25 000.00 TRY (минорные единицы — куруш, 2 знака). target_requisite пуст всегда для PayIn — это поле payout-сделок; реквизиты получателя (IBAN, держатель, банк) клиент получает на платёжной странице (см. ниже).

Статусы PayIn сделки

Канонический жизненный цикл — domain.OrderStatus (11 значений, UPPER_SNAKE). Полная таблица с V1-кодами — в Справочнике статусов.

Отмена сделки (Cancel)

PayIn-сделку можно явно отменить до подтверждения платежа — статус переходит в терминальный CANCELLED. Отмена доступна из INITIALIZED, ESCROW_LOCKED и PAYMENT_NOTIFIED; после PAYMENT_VERIFIED (и тем более из COMPLETED/APPEALED и прочих состояний) отмена невозможна — платёж уже подтверждён трейдером.

Два эндпоинта, один и тот же переход FSM:

Отмена мерчантом

POST /api/v1/p2p/merchant/deals/{deal_id}/cancel

Аутентификация — стандартная HMAC-пара мерчанта (X-Merchant-Token / X-Signature, как у остальных /merchant/*-эндпоинтов). Тело:

Ответ 200 OK — объект MerchantDealInfo отменённой сделки в поле deal (та же структура, что у GET /deals/{deal_id}, со status: "CANCELLED").

Отмена игроком (платёжная страница)

POST /api/v1/p2p/checkout/{hash}/cancel

Публичный эндпоинт по checkout-хэшу из payment_url (авторизация не нужна, тело пустое) — вызывается кнопкой отмены на hosted payform. Возвращает обновлённый CheckoutView.

Правила и коды ответов

• Отмена после ESCROW_LOCKED автоматически снимает эскроу-холды (order-level + per-match) — деньги «размораживаются» без участия мерчанта.
• fee_breakdown обнуляется, матчи сделки переходят в FAILED (та же fail-family семантика, что у EXPIRED).
• О факте отмены приходит webhook deal.cancelled (см. Callbacks).

Расхождения сумм (full / partial / overpaid)

Фактическая сумма, переведённая плательщиком, сверяется с суммой сделки: результат фиксируется в полях received_amount (минорные единицы) и amount_match_status сделки и передаётся в вебхуках после верификации.

Изменение суммы сделки (amend)

Пока сделка живая (статусы INITIALIZED, ESCROW_LOCKED, PAYMENT_NOTIFIED, SOFT_DISPUTED — всё до PAYMENT_VERIFIED), оператор платформы может изменить её фиатовую сумму: при частичной оплате, ошибке мерчанта в сумме и т.п. Это операторское действие кабинета (не merchant-API):

POST /api/v1/p2p/deals/{deal_id}/amount

Что происходит при amend (атомарно, одной транзакцией):

• amount_usdt пересчитывается по курсу самой сделки (exchange_rate_micro, зафиксирован при создании — условия акта не меняются);
• эскроу-холды пересоздаются под новую сумму: order-level + все per-match (идемпотентные ключи холдов производны от (deal_id, amount_version));
• amount_version увеличивается на 1 (если передан expected_amount_version и он не совпал — отказ 409);
• пишется неизменяемая (INSERT-only) аудиторская строка p2p_deal_amount_changes и эмитится событие deal.amount_changed (только V2).

После PAYMENT_VERIFIED изменение суммы невозможно — сумма уже авторизована; расхождения закрываются сеттлментом (ниже) или возвратом.

Зачёт просроченного платежа (Settle-as-Received)

Сделка в EXPIRED не оживает никогда (терминальные статусы неизменяемы). Если к моменту истечения платёж фактически пришёл (received_amount > 0, обычно amount_match_status = partial/overpaid), оператор закрывает спор зачётом: по резолву апелляции создаётся новая сделка-сеттлмент:

POST /api/v1/p2p/appeals/{appeal_id}/settlement

Свойства сеттлмента:

• это новый deal_id со связями parent_deal_id (истёкший оригинал) и origin_appeal_id (одна апелляция → максимум один сеттлмент, UNIQUE);
• сумма = received_amount оригинала; курс — новый, на момент резолва (фиксируется в записи сеттлмента);
• путь денег стандартный: эскроу-холд → verify → complete одним действием, комиссия/леджер считаются как у обычной сделки;
• по сеттлменту приходит полный набор вебхуков deal.created … deal.completed (обе версии API);
• апелляция резолвится SATISFIED с ссылкой на сеттлмент в resolution_note;
• оригинал остаётся EXPIRED навсегда, его received_amount сохраняется как исторический факт. Листинги показывают обе записи со связью (parent_deal_id).

Требования: родитель EXPIRED, апелляция в OPEN/IN_PROGRESS/REOPENED, received_amount > 0 (или обоснованный override). Нарушения → 409/400.

Поддерживаемые методы оплаты

Доступные методы определяются конфигурацией тенанта (таблица p2p_payment_methods). При создании платежа передайте ссылку на метод в поле payment_method_id: UUID (канонический формат — поле id каталога) или слаг (поле slug). Канонический источник обеих форм — мерчантский эндпоинт GET /api/v1/p2p/merchant/payment-methods: он возвращает методы вашего тенанта с их id (UUID), slug, name, requisite_types, currency_code и status (см. Banks → Получение списка методов через API). Неизвестный UUID/слаг отклоняется с 400 INVALID_ARGUMENT, в тексте ошибки перечислены допустимые слаги активных методов.

Типичные каналы (в payment_method_id передавайте id (UUID) или slug конкретного метода вашего тенанта из GET /payment-methods — канонические слаги каталога, например sbp_rub, card_rub, mobcom_rub, express-havale):

• СБП — перевод по телефону. RequisiteType: SBP (слаг каталога — sbp_rub).
• Перевод по номеру карты. RequisiteType: BANK_CARD (слаг — card_rub).
• Быстрая оплата Сбербанк/Т-Банк. RequisiteType: BANK_CARD / SBP.
• Методы мобильной коммерции — пополнение счёта мобильного оператора (RequisiteType: SIM; слаг — mobcom_rub). Реквизит для плательщика — номер телефона оператора связи; название оператора отображается на платёжной странице как «банк получателя». Номер телефона самого плательщика (MSISDN) для оплаты не требуется и никуда не передаётся: перевод выполняется плательщиком из своего мобильного приложения банка.
• Международный перевод по IBAN (ISO 13616) для не-RU рынков (TRY, EUR, ...). RequisiteType: BANK_TRANSFER (слаг вида express-havale — задаётся при заведении метода для вашего тенанта).

Где реквизиты получателя при PayIn

Реквизиты получателя (номер карты, телефон СБП, IBAN для BANK_TRANSFER) никогда не возвращаются в теле ответа POST /deals/payin — там есть только deal_id и payment_url (PII-минимизация: платёжные данные не покидают платёжный контур).

Клиент получает реквизиты, открывая payment_url: платёжная страница дёргает публичный эндпоинт

GET /api/v1/p2p/checkout/{hash}

где {hash} — 64-hex идентификатор из payment_url (capability-токен, авторизация не нужна). В ответе (CheckoutView):

Полный контракт CheckoutView и пример ответа — в SDK Examples §9; экран IBAN-оплаты описан в Hosted Checkout → Перевод по IBAN. В терминальных состояниях (COMPLETED, EXPIRED, ...) чувствительные поля обнуляются.

Пример на curl

curl -X POST https://api.syncra.money/api/v1/p2p/merchant/deals/payin \
  -H "X-Merchant-Token: your_token_here" \
  -H "X-Timestamp: 1783856120" \
  -H "X-Signature: t=1783856120,v1=9e87d0c3c8801d0a5198d023b6b19a16f2c8d2037920ab3e09819cd8e412cfab" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "RUB",
    "payment_method_id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "my_unique_p2p_key_001"
  }'

События вебхуков

При создании PayIn генерируются следующие события (отправляются на ваш callback URL):