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