API интеграция P2P платежей в 2026: Полное руководство разработчика от первого запроса до продакшна

Интеграция платежного API кажется простой задачей, пока не столкнешься с ней на практике. Прочитать документацию, отправить POST-запрос, получить ответ — звучит как час работы. Но когда дело доходит до обработки статусов, колбэков, ошибок и исключительных ситуаций, выясняется, что час превращается в неделю.

За три года интеграции P2P платежей для разных проектов я выработал подход, который позволяет пройти путь от первого запроса до стабильно работающего продакшна за 2-3 дня. В этой статье — пошаговая инструкция для разработчика.

Шаг 1: Регистрация и получение доступа

Первое, что нужно сделать — зарегистрироваться на P2P платформе и получить доступ к админке. В разделе Интеграция вы найдете:

• merchant_id — уникальный идентификатор вашего магазина в системе.
• Access-Token — ключ для аутентификации API запросов.

Базовый URL для всех запросов к API — https://payshark.eu. Все запросы выполняются по HTTPS. Формат данных — JSON.

Каждый запрос должен содержать обязательные заголовки:

• Accept: application/json
• Access-Token: ваш_токен

Дополнительно можно указать X-Max-Wait-Ms — максимальное время ожидания ответа в миллисекундах. Минимальное значение — 1000 мс.

Шаг 2: Изучение доступных методов

Прежде чем создавать первую сделку, нужно изучить, какие валюты и платежные методы доступны.

GET /api/currencies — возвращает список валют с параметрами: код (rub, kzt, byn), precision (точность), symbol (₽, ₸, Br).

GET /api/payment-gateways — возвращает список банков с подробной информацией:

• name — название банка (Сбербанк, Альфа-Банк, Kaspi Bank).
• code — код метода для передачи в запросах.
• min_limit — минимальная сумма сделки.
• max_limit — максимальная сумма сделки.
• reservation_time — время резервирования реквизитов в минутах.
• detail_types — типы реквизитов (card, account_number, phone).
• commission — комиссии по сделкам и выплатам.

Эти данные нужно закешировать на стороне магазина и обновлять раз в сутки, так как список методов и лимиты могут меняться.

Шаг 3: Создание первой сделки

Для создания сделки используется POST-запрос:

POST /api/merchant/order

Параметры запроса:

• merchant_id — ваш UUID из админки.
• external_id — ID заказа в вашей системе.
• amount — сумма в минимальных единицах валюты (рубли в копейках).
• payment_gateway — код банка из /api/payment-gateways.
• payment_detail_type — тип реквизитов: card, account_number, phone.
• callback_url — URL для уведомлений об изменении статуса.

Пример запроса на curl:

curl -X POST 'https://payshark.eu/api/merchant/order' -H 'Accept: application/json' -H 'Access-Token: {token}' -d 'merchant_id=UUID' -d 'external_id=123' -d 'amount=100000' -d 'payment_gateway=sberbank' -d 'payment_detail_type=card' -d 'callback_url=https://mysite.com/payment/callback'

В ответ приходят реквизиты для оплаты: номер карты, получатель, сумма к переводу. Эти данные нужно отобразить клиенту на странице заказа.

Шаг 4: Обработка callback уведомлений

После того как клиент перевел деньги, P2P платформа отправляет POST-запрос на callback_url. Ваша система должна:

1. Принять запрос и вернуть HTTP 200 как можно быстрее.
2. Проверить, что это не дубликат (дедупликация по ID уведомления).
3. Обработать изменение статуса.

Основные статусы:

• waiting_for_payment — клиенту показаны реквизиты, ожидается перевод.
• successfully_paid — платеж поступил, можно подтверждать заказ.
• expired — клиент не перевел деньги вовремя.
• cancelled — сделка отменена.

Обработку колбэков нужно делать асинхронно — вернуть 200 сразу, а бизнес-логику выполнить в фоновой очереди.

Шаг 5: Обработка ошибок API

API может возвращать разные HTTP статусы:

• 200 — успех. Поле success: true.
• 422 — ошибка валидации. Проверьте параметры запроса.
• 400 — бизнес-ошибка. Например, Подходящие платежные реквизиты не найдены.
• 500 — внутренняя ошибка сервера. Повторите запрос через несколько секунд.
• 504 — тайм-аут. Запрос не обработан за время X-Max-Wait-Ms. Повторите.

Для ошибок 500 и 504 реализуйте повторные попытки с экспоненциальной задержкой: 1 секунда, 3 секунды, 10 секунд, 30 секунд.

Шаг 6: Проверка статуса сделки

Если колбэк по какой-то причине не пришел, можно проверить статус через GET запрос:

GET /api/merchant/order?order_id=ID_СДЕЛКИ

Возвращает полную информацию о сделке, включая текущий статус и историю изменений. Рекомендуется использовать этот метод как дополнительную страховку при создании и проверке заказов.

Шаг 7: Тестирование перед запуском

Перед запуском в продакшн протестируйте все сценарии:

1. Создание сделки с корректными параметрами — должна вернуть реквизиты.
2. Создание сделки с суммой выше лимита — должна вернуть ошибку 400.
3. Создание сделки с неверным токеном — должна вернуть ошибку 401.
4. Обработка callback со статусом success — заказ должен подтвердиться.
5. Обработка callback со статусом expired — заказ должен отмениться.
6. Проверка статуса через GET — должна вернуть актуальный статус.

Заключение

Интеграция P2P платежного API — задача на 2-3 дня для опытного разработчика. Регистрация, изучение доступных методов, реализация создания сделок, обработка колбэков и тестирование — пять шагов, которые превращают платежную интеграцию в стабильно работающий механизм.

P2P платформы, такие как PayShark, предоставляют полную документацию с примерами запросов и ответов. Четкое следование API спецификации и правильная обработка статусов — залог успешной интеграции, которая будет работать без сбоев годами.