protopays · API

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 задаёт метод (например СБП); сервер приводит его к внутренней схеме. Полный список полей — в справочнике по созданию платежа.

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",
      "type": "trusted",
      "payments": {
        "successful": 5,
        "expired": 1
      }
    }
  }'

Пример ответа (успешное создание; для СБП реквизит типично телефон):

{
  "message": "Payment created",
  "data": {
    "id": 1001,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "demo-001",
    "status": "pending",
    "amount": "1000.00",
    "currency": "RUB",
    "requisite": {
      "value": "+79991234567",
      "holder": "И. Иванов",
      "bank": "Пример банк"
    },
    "expiresAt": "2026-04-20T15:30:00+00:00"
  }
}

Что взять из ответа: поле message — признак успешной операции; в data сохраните id и uuid для учёта, status — текущее состояние; requisite — что показать плательщику (значение зависит от метода); expiresAt — крайний срок резерва реквизита. Итоговое подтверждение оплаты приходит через webhook; подробнее — реквизиты.

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

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

Важно

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

Далее

OpenAPI (JSON): /openapi/api-docs.json