PayMorgan.pro — Merchant API Documentation

🔐 Аутентификация (HMAC)

Все запросы к API (кроме входа в веб-панель) требуют криптографической подписи для защиты от Replay-атак и целостности данных.

HEAD

Передавать в каждом запросе

Заголовок	Тип	Описание
`X-Api-Key`	string	Публичный ID ключа из админ-панели
`X-Timestamp`	string	UNIX-время в секундах. Допустимо отклонение ±5 мин
`X-Signature`	string	`HMAC-SHA256` тела запроса, вычисленный с `Secret Key`

⚠️ Strict Mode: Тело запросов строго типизировано (additionalProperties: false). Любые неизвестные поля вызовут ошибку 400 или 422.

💳 Платежи

🟢 Создать платеж

POST

/api/v1/merchant/payments

Создает транзакцию, возвращает ссылку на оплату или реквизиты.

Параметр	Тип	Описание
`merchant_order_id` *	string	Ваш ID заказа (макс. 128)
`amount` *	number	Сумма платежа (>0)
`currency` *	string	Валюта (`RUB`, `USDT` и др.)
`payment_method` *	string	Код метода (`card`, `usdt_trc20`)
`idempotency_key`	string	Уникальный ключ для защиты от дублей
`success_url`, `cancel_url`, `callback_url`	string	URL-адреса редиректов и вебхуков
`description`, `meta`	string, object	Описание и произвольные метаданные

Запрос (cURL)

curl -X POST "https://api.paymorgan.pro/api/v1/merchant/payments" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_test_..." \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: $(echo -n '{"merchant_order_id":"ORD-1","amount":100,"currency":"RUB","payment_method":"card"}' | openssl dgst -sha256 -hmac "YOUR_SECRET_KEY")" \
  -d '{
    "merchant_order_id": "ORD-1001",
    "amount": 1500.00,
    "currency": "RUB",
    "payment_method": "card",
    "idempotency_key": "unique-key-99",
    "success_url": "https://shop.com/success",
    "meta": {"order_type": "digital"}
  }'

Ответ (200 OK)

{
  "payment_id": "pay_8f7a6b...",
  "status": "pending",
  "requested_amount": "1500.00",
  "requested_currency": "RUB",
  "base_amount_usdt": "16.50",
  "rate_to_usdt": "90.909090",
  "expires_at": "2026-05-04T12:00:00Z",
  "payment_url": "https://pay.paymorgan.pro/pay/pay_8f7a6b..."
}

📋 Список методов оплаты

GET

/api/v1/merchant/payments/methods

Возвращает доступные методы без раскрытия внутренних провайдеров или комиссий.

Ответ (200 OK)

{
  "direction": "payin",
  "methods": [
    { "code": "card", "name": "Bank Cards", "currencies": ["RUB", "KZT"] },
    { "code": "usdt_trc20", "name": "USDT (TRC20)", "currencies": ["USDT"] },
    { "code": "sbp", "name": "Fast Payment System", "currencies": ["RUB"] }
  ]
}

📊 Получить статус платежа

GET

/api/v1/merchant/payments/{payment_id}

Возвращает детальный статус, реквизиты для перевода и параметры редиректа.

Ответ (200 OK)

{
  "payment_id": "pay_8f7a6b...",
  "status": "completed",
  "payment_method": "card",
  "requisites": null,
  "checkout_url": "https://pay.paymorgan.pro/checkout/pay_8f7a6b...",
  "redirect_method": "GET"
}

💼 Кошельки

GET

/api/v1/merchant/wallets

Возвращает балансы всех кошельков, привязанных к мерчанту. Доступен фильтр ?currency=USDT.

Ответ (200 OK)

{
  "merchant_id": "merch_abc123",
  "wallets": [
    {
      "wallet_public_id": "wal_usdt_001",
      "currency": "USDT",
      "balance": "1000.000000",
      "reserved": "50.000000",
      "available": "950.000000",
      "status": "active",
      "updated_at": "2026-05-04T10:00:00Z"
    }
  ]
}

🔔 Вебхуки и Колбэки

POST

/api/v1/merchant/webhooks/config

Настройка автоматических уведомлений. URL-адреса валидируются (localhost и private IP запрещены).

Запрос настройки

{
  "status_url": "https://api.mysite.com/webhooks/paymorgan",
  "success_url": "https://mysite.com/payment/success",
  "callback_secret": "super_secret_key_min_16_chars",
  "enabled": true,
  "retry_count": 5,
  "retry_interval_seconds": 60
}

💡 Альтернативный поллинг: Для проверки статуса без вебхуков используйте
GET /api/v1/merchant/webhooks/payments/{payment_id}/status

⛔ Обработка ошибок

Все ошибки возвращаются в формате MerchantApiErrorResponse.

Пример ошибки (422)

{
  "success": false,
  "code": "validation_error",
  "message": "Invalid input",
  "details": [
    { "loc": ["body", "amount"], "msg": "Ensure this value is greater than 0." }
  ]
}

Код	Описание
`400`	Структурная ошибка запроса
`401`	Неверная HMAC-подпись или истекший timestamp
`409`	Дубликат `idempotency_key` или `merchant_order_id`
`422`	Ошибка валидации значений полей
`429`	Превышен лимит запросов (Rate Limit)

💡 Рекомендации по интеграции

Idempotency: Всегда генерируйте уникальный idempotency_key. При обрыве сети повторный запрос не создаст двойной платеж.
Валидация вебхуков: Проверяйте подпись входящих колбэков, используя ваш callback_secret.
Срок действия: Платежи имеют expires_at. Не позволяйте клиентам оплачивать просроченные ссылки.
Учет: Используйте base_amount_usdt в ответах для внутренней бухгалтерии, если работаете в стейблкоинах.

Документация сгенерирована на основе OpenAPI 3.1.0 (v2.3.0) • PayMorgan.pro