H2H API для P2P платежей в 2026: Полное руководство по управлению сделками, спорами и балансом для финтех-платформ
Merchant API хорош для быстрого старта, но когда бизнес вырастает — появляются задачи, которые простая версия API решить не может. Нужно закрывать сделки вручную, открывать споры, загружать чеки, управлять балансом. Для этого существует H2H API (Head-to-Head) — расширенная версия, которая дает полный контроль над платежами.
В этой статье — полный разбор H2H API: все эндпоинты, параметры, статусы и примеры использования.
Чем H2H отличается от Merchant API
Merchant API позволяет создавать сделки, получать реквизиты и обрабатывать колбэки. Этого достаточно для интернет-магазина с типовым процессом оплаты.
H2H API добавляет возможности, критически важные для финтех-платформ, криптообменников и крупных мерчантов:
- Закрытие сделок вручную после проверки поступления средств.
- Управление спорами — открытие, отслеживание, разрешение.
- Загрузка подтверждающих документов (чеки, скриншоты).
- Полный контроль над балансом и выводами средств.
- Более детальная информация по каждой сделке.
Важное отличие: для сделок, созданных через H2H API, не предоставляется платежная ссылка. Все реквизиты нужно показывать клиенту самостоятельно.
Создание сделки через H2H API
Для создания сделки используется POST-запрос:
POST /api/order
Параметры те же, что и в Merchant API: merchant_id, external_id, amount, payment_gateway, payment_detail_type, callback_url.
Разница в ответе: H2H API возвращает больше данных, включая полную информацию о трейдере и расширенную историю статусов.
Пример запроса:
curl -X POST 'https://payshark.eu/api/order' -H 'Accept: application/json' -H 'Access-Token: {token}' -d 'merchant_id=UUID' -d 'external_id=456' -d 'amount=500000' -d 'payment_gateway=sberbank' -d 'payment_detail_type=card' -d 'callback_url=https://mysite.com/callback'
Получение информации о сделке
В любой момент можно проверить статус сделки:
GET /api/order?order_id=ID_СДЕЛКИ
Возвращает: id, external_id, status, sub_status, amount, currency, payment_gateway, payment_details, callback_url, created_at, history (массив всех изменений статуса с временными метками).
Поле history особенно ценно для финтех-платформ. Оно позволяет отследить весь жизненный цикл сделки от создания до завершения.
Закрытие сделки вручную
Одно из ключевых преимуществ H2H API — возможность закрывать сделки вручную. Это нужно, когда автоматическое закрытие не сработало, или когда требуется проверка перед подтверждением.
POST /api/order/close
-d 'order_id=ID_СДЕЛКИ'
После закрытия сделка переводится в статус success. Используется, например, когда трейдер подтвердил поступление средств, но колбэк по какой-то причине не пришел.
Управление спорами
Самый важный функционал H2H API для финтех-платформ. Если возник спор между участниками сделки, мерчант может открыть его через API.
Открытие спора:
POST /api/order/dispute
-d 'order_id=ID_СДЕЛКИ'
После открытия сделка переводится в статус dispute. Администраторы P2P платформы подключаются к разбирательству.
Получение информации о споре:
GET /api/order/dispute?order_id=ID_СДЕЛКИ
Возвращает статус спора, историю сообщений, приложенные документы и текущее состояние разбирательства.
Загрузка подтверждающих документов:
POST /api/order/check
-F 'order_id=ID_СДЕЛКИ'
-F 'file=@check.jpg'
Чек, скриншот перевода или любой другой документ, подтверждающий оплату, прикрепляется к сделке и становится доступен администраторам.
Управление балансом
H2H API предоставляет полный контроль над финансами:
Проверка баланса:
GET /api/balance
Возвращает доступный баланс в разрезе всех валют, заблокированные средства и доступные для вывода суммы.
Создание запроса на вывод:
POST /api/withdrawal
-d 'amount=100000'
-d 'currency=rub'
-d 'payment_details={"card_number":"1234567890123456"}'
Автоматический вывод:
Настраивается в админке. Средства автоматически перечисляются на указанные реквизиты при достижении порога или по расписанию.
Callback-уведомления в H2H API
Колбэки в H2H API отправляются по тем же правилам, что и в Merchant API, но содержат больше данных. В уведомление включается расширенная информация о сделке, включая историю изменений.
Приоритет callback_url: URL, переданный при создании сделки, имеет приоритет над URL из настроек админки.
Практический пример: криптообменник на H2H
Криптообменник, интегрировавший H2H API, работает по следующему сценарию:
- Клиент хочет купить USDT за рубли. Создается сделка через POST /api/order.
- Клиент переводит рубли на реквизиты трейдера.
- Трейдер подтверждает получение. Обменник проверяет через GET /api/order.
- Если все корректно, обменник отправляет USDT клиенту и закрывает сделку через POST /api/order/close.
- Если возникли проблемы, обменник открывает спор через POST /api/order/dispute.
Заключение
H2H API — это правильный выбор для любого бизнеса, которому нужен полный контроль над платежами. Закрытие сделок вручную, управление спорами, загрузка документов и контроль баланса — возможности, которые превращают P2P платежи из простого шлюза в полноценную платежную инфраструктуру.
PayShark предоставляет H2H API с полной документацией и поддержкой. Интеграция занимает 3-5 дней и дает бизнесу все инструменты для профессионального управления платежами.
