UNION-листинг PayIn и PayOut, детали сделки, фильтры и пагинация в Syncra Merchant API V2

Управление и мониторинг сделок (Deals)

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

Детали конкретной сделки

GET /api/v1/p2p/merchant/deals/{deal_id}

Параметры пути (Path Parameters)

Имя	Тип	Обяз.	Описание
`deal_id`	string(UUID)	Да	Системный идентификатор сделки (например, `9512d99a-3bbc-4a32-acae-d6ad8bb7e32f`).

Пример успешного ответа (`200 OK`)

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

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

Поля `MerchantDealInfo` (proto)

Поле	Тип	Описание
`deal_id`	string(UUID)	Идентификатор сделки. Всегда `deal_id`, не `id`.
`status`	string	Статус: `OrderStatus` (PayIn) или `PayOutStatus` (PayOut) — полный список в Справочнике статусов.
`amount`	int64	Сумма в минорных единицах (копейки/центы/satoshi).
`currency`	string	ISO 4217 код валюты.
`created_at`	string(RFC3339)	Время создания сделки (UTC).
`client_id`	string	ID плательщика в системе мерчанта (может быть пустым).
`deal_type`	string	Направление: `"PAYIN"` или `"PAYOUT"`.
`updated_at`	string(RFC3339)	Время последнего обновления (UTC).
`payment_url`	string	URL hosted payform (`{checkout_base}/pay/{hash}`). Заполнен только для PayIn; пуст для PAYOUT.
`target_requisite`	string	Реквизиты получателя (эхо из запроса выплаты, без маскировки). Заполнены только для PAYOUT; пусты для PayIn.
`received_amount`	int64	Фактически поступившая от плательщика сумма (данные сверки от банка/провайдера). `0`/пусто, пока сверка не отчиталась. Только PayIn.
`amount_match_status`	string	Результат сверки сумм: `full` / `partial` / `overpaid` (строго lowercase; `partial` = поступило меньше заявленного); пусто, если сверка не выполнялась. Только PayIn.

idempotency_key не входит в MerchantDealInfo proto и не возвращается в ответе. Это внутреннее поле запроса, используемое только для идемпотентности создания сделки.

Список сделок (UNION-листинг)

Постраничная история платежей и выплат с фильтрацией по датам, статусам и типам операций. Листинг — объединение двух источников: входящих платежей (p2p_orders, deal_type=PAYIN) и выплат (p2p_payouts, deal_type=PAYOUT) в единый хронологический список (новее — раньше).

GET /api/v1/p2p/merchant/deals

Параметры фильтрации (Query Parameters)

Поле	Тип	Обяз.	Описание
`deal_type`	string	Нет	Тип операции: `"PAYIN"` или `"PAYOUT"`. Без фильтра возвращаются оба направления.
`statuses`	array	Нет	Имена статусов БД (повторяющийся параметр, например `statuses=COMPLETED&statuses=EXPIRED`). PayIn: `INITIALIZED`, `ESCROW_LOCKED`, `PAYMENT_NOTIFIED`, `PAYMENT_VERIFIED`, `COMPLETED`, `EXPIRED`, `APPEALED`, `REFUND_PENDING`, `SPAM_REJECTED`, `SOFT_DISPUTED`, `CANCELLED`; PayOut: `INITIALIZED`, `MATCHED`, `UNASSIGNED`, `PROCESSING`, `COMPLETED`, `FAILED`, `EXPIRED`.
`created_after`	string(RFC3339)	Нет	Нижняя граница времени создания (включительно).
`created_before`	string(RFC3339)	Нет	Верхняя граница времени создания (включительно).
`page_size`	int32	Нет	Элементов на странице (по умолчанию `50`, максимум `250`).
`page_token`	string	Нет	Непрозрачный курсор следующей страницы из предыдущего ответа (`next_page_token`). Пустая строка = первая/последняя страница (AIP-158).
`merchant_id`	string(UUID)	Нет	Advisory-поле: молча игнорируется (см. примечание ниже).

GET /deals?merchant_id=<любой> (в теле или query) молча игнорируется: реальный скоуп всегда определяется HMAC-идентичностью из подписанного токена (claims-win). Поле merchant_id — advisory для admin-имперсонации; при обычной HMAC-аутентификации переданное значение (в т.ч. невалидного формата или чужое) не влияет на результат и не вызывает ошибки.

Пример ответа (`200 OK`, живой ответ стейджа)

{
  "data": [
    {
      "deal_id": "9512d99a-3bbc-4a32-acae-d6ad8bb7e32f",
      "status": "EXPIRED",
      "amount": "100000",
      "currency": "RUB",
      "created_at": "2026-08-23T19:04:28Z",
      "client_id": "",
      "deal_type": "PAYIN",
      "updated_at": "2026-08-23T19:14:34Z",
      "payment_url": "",
      "target_requisite": "",
      "received_amount": "0",
      "amount_match_status": ""
    },
    {
      "deal_id": "7e40a4f8-b4ec-406c-8bb1-1e1ab4949a2f",
      "status": "MATCHED",
      "amount": "96971",
      "currency": "RUB",
      "created_at": "2026-08-23T19:04:17Z",
      "client_id": "",
      "deal_type": "PAYOUT",
      "updated_at": "2026-08-23T19:04:17Z",
      "payment_url": "",
      "target_requisite": "2202201234567890",
      "received_amount": "0",
      "amount_match_status": ""
    }
  ],
  "next_page_token": "2026-08-23T19:04:17Z|7e40a4f8-b4ec-406c-8bb1-1e1ab4949a2f"
}

Поля ответа

Поле	Тип	Описание
`data`	`MerchantDealInfo[]`	Страница сделок; структура элементов идентична `GET /deals/{deal_id}`.
`next_page_token`	string	Курсор следующей страницы. Пустая строка = последняя страница. Трактуйте как opaque — формат меняется.

Листинг отдаётся канон-конвертом {"data": [...], "next_page_token": ""} (как и все списки Merchant API — см. Обзор). Иных полей конверт не несет: total_count существует только во внутреннем gRPC-контракте и на HTTP не отдаётся — размер выборки считайте по странице/агрегатам оборотов. payment_url присутствует только у PAYIN-сделок, target_requisite — только у PAYOUT-сделок (эхо реквизитов получателя из запроса выплаты, без маскировки). received_amount / amount_match_status заполняются только после сверки поступлений (PayIn).

Пагинация и граничные случаи

Битый page_token → 400 Bad Request (problem+json, живой ответ):

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "{\"code\":3,\"message\":\"invalid page_token\",\"details\":[]}",
  "instance": "/api/v1/p2p-engine"
}

Неизвестные значения фильтров (deal_type=BOGUS, statuses=NOT_A_STATUS) не вызывают ошибку — возвращается 200 с пустым data и next_page_token: "".
Чужой deal_id в GET /deals/{deal_id} → 404 Not Found (deal not found) — IDOR-защита схлопывает «не существует» и «чужое» в один ответ.

Статистика сделок (Planned)

Эндпоинт статистики не реализован в текущей версии API. Метод POST /api/v1/p2p/merchant/deals/statistics отсутствует в gRPC-спецификации и вернёт 404 Not Found до момента реализации. Для агрегатов используйте обороты, для выгрузки — CSV-экспорт. Следите за changelog для обновлений.

В качестве альтернативы используйте GET /deals с фильтрами created_after / created_before и statuses, обороты по дням или CSV-экспорт и агрегируйте данные на стороне клиента.

История и детали сделок (Deals)