protopaysAPI
В кабинет

ProtoPays API — платёжная система

Принимайте платежи и получайте уведомления о статусах транзакций через простой HTTP API. Ниже — вход за пару минут; детали протокола — в разделах справочника.

Базовый URL

Все запросы отправляются на:

Остальные пути в документации — относительные (без слэша в конце Base URL).

https://api.protopays.io

Пример: POST /api/v1/payments → Base URL + /api/v1/payments

Быстрый старт

Интеграция занимает ~10–15 минут

  1. Получите API ключ в личном кабинете (шлюз → credentials): публичный key_id и секрет.
  2. Сформируйте Signature — HMAC-SHA256 по байтам тела; передайте в заголовках X-Merchant-Key-Id, X-Merchant-Secret и Signature (зачем все три — в аутентификация).
  3. Отправьте POST /api/v1/payments с JSON телом.
  4. Получите webhook со статусом на URL из поля callbackUri.

Пошагово с кодом: первый запрос.

Пример запроса (минимальный)

Создадим тестовый платёж:

Поле method — способ оплаты (например sbp). Полный список — в создании платежа.

curl
curl -X POST 'https://api.protopays.io/api/v1/payments' \
  -H 'Content-Type: application/json' \
  -H 'X-Merchant-Key-Id: <KEY_ID>' \
  -H 'X-Merchant-Secret: <SECRET>' \
  -H 'Signature: <SIGNATURE>' \
  -d '{
    "orderId": "demo-001",
    "amount": "1000",
    "currency": "RUB",
    "callbackUri": "https://your-site.example/hooks/protopays",
    "method": "sbp",
    "payer": {
      "userId": "u-4095",
      "userIp": "188.11.55.10",
      "fullName": "Kim Min-jun",
      "type": "trusted",
      "payments": {
        "successful": 5,
        "expired": 1
      }
    }
  }'

Пример ответа:

json
{
  "message": "Payment created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "demo-001",
    "status": "pending",
    "amount": "1000.00",
    "currency": "RUB",
    "method": "sbp",
    "requisite": {
      "value": "+79991234567",
      "holder": "И. Иванов",
      "bank": "Пример банк"
    },
    "paymentPageUrl": "https://pay.protopays.io/r/rpt_<token>",
    "expiresAt": "2026-04-20T15:30:00+00:00"
  }
}

Покажите плательщику requisite, дождитесь webhook. Срок — в expiresAt.

Основные сущности

  • Payment — приём платежа от покупателя
  • Payin — выплата на реквизит (/api/v1/payins)
  • Deposit — пополнение кассы
  • Webhook — исходящее уведомление о статусе

Важно

  • Подпись считается от точного JSON: любой лишний пробел или другой порядок полей при пересборке тела сломает подпись.
  • Webhooks могут приходить повторно — обрабатывайте их идемпотентно (по uuid / id платежа).
  • Используйте стабильный orderId, чтобы не создавать дублирующие платежи при повторах — см. идемпотентность.

Далее