Документация Paygrator API

Paygrator API позволяет платформам создавать QR-коды СБП, принимать платежи по подписке, получать статусы операций и выполнять возвраты.

Аутентификация

Каждый запрос должен содержать заголовок X-Api-Token с токеном платформы. Токен выдаётся администратором системы и привязан к контракту платформы.

X-Api-Token: ваш_токен_платформы

Ограничение по IP-адресам

Для каждого токена администратор может задать список разрешённых IP-адресов. Если список задан — запросы с любых других адресов будут отклонены с кодом 401 Unauthorized до проверки самого токена.

Список задаётся строкой с IP-адресами через запятую:

192.168.1.10, 10.0.0.5, 203.0.113.42

Лимиты

Каждый контракт платформы имеет два ограничения, задаваемых администратором:

При превышении любого лимита запрос возвращает 400 Bad Request с описанием причины в поле error.

Формат ошибок

При ошибке сервер возвращает HTTP 400 Bad Request с телом:

{
  "errorCode":    "КОД_ОШИБКИ",   // код банка или внутренний (может быть null)
  "errorMessage": "Описание"      // читаемое сообщение об ошибке
}

Возможные внутренние ошибки:

POST /api/payments/qr/onetime

Создаёт одноразовый QR-код СБП для приёма оплаты. После первой успешной оплаты QR-код переходит в статус ACCEPTED и становится недействительным.

Тело запроса

{
  "amount":         10000,                  // сумма в копейках (обязательно)
  "currency":       "RUB",                  // валюта ISO 4217 (обязательно)
  "purpose":        "Оплата заказа #1234",  // назначение платежа (опционально)
  "redirectUrl":    "https://example.com/return", // URL редиректа после оплаты (опционально)
  "ttlMinutes":     15,                     // время жизни QR в минутах (опционально)
  "imageMediaType": "image/png",            // формат изображения: "image/png" или "image/svg+xml" (опционально)
  "imageSize":      300                     // размер изображения в пикселях 200–1000, по умолчанию 300 (опционально)
}

Успешный ответ 200 OK

{
  "isSuccess":      true,
  "uniQrId":        "A2B3C4D5E6F7...",    // идентификатор QR в системе банка
  "payload":        "https://qr.nspk.ru/...", // SBP-ссылка для генерации QR
  "status":         "CREATED",
  "imageMediaType": "image/png",           // null если imageMediaType не был передан
  "imageContent":   "iVBORw0KGgo...",     // QR-изображение в base64, null если не запрошено
  "errorCode":      null,
  "errorMessage":   null
}

POST /api/payments/qr/reusable

Создаёт многоразовый QR-код для привязки счёта плательщика (C2B Подписка). Плательщик сканирует QR, подтверждает привязку — после этого можно инициировать списания без повторного сканирования.

Тело запроса

{
  "purpose":        "Ежемесячная подписка",       // назначение (обязательно)
  "redirectUrl":    "https://example.com/return", // URL редиректа после привязки (опционально)
  "amount":         50000,                        // фиксированная сумма списания в копейках (опционально)
  "currency":       "RUB",                        // валюта, обязательна при указании amount (опционально)
  "ttlMinutes":     1440,                         // время жизни QR в минутах (опционально)
  "imageMediaType": "image/png",                  // формат изображения: "image/png" или "image/svg+xml" (опционально)
  "imageSize":      300                           // размер изображения в пикселях 200–1000, по умолчанию 300 (опционально)
}

Успешный ответ 200 OK

{
  "isSuccess":      true,
  "uniQrId":        "A2B3C4D5E6F7...",
  "payload":        "https://qr.nspk.ru/...",
  "status":         "CREATED",
  "imageMediaType": "image/png",           // null если imageMediaType не был передан
  "imageContent":   "iVBORw0KGgo...",     // QR-изображение в base64, null если не запрошено
  "errorCode":      null,
  "errorMessage":   null
}

GET /api/payments/qr/status

Возвращает текущий статус одного или нескольких QR-кодов. Можно опрашивать до получения финального статуса (ACCEPTED / REJECTED).

Query-параметры

Пример запроса

GET {BASE_URL}/api/payments/qr/status?uniQrIds=A2B3C4D5E6F7
X-Api-Token: ваш_токен_платформы

Успешный ответ 200 OK

{
  "isSuccess": true,
  "items": [
    {
      "uniQrId": "A2B3C4D5E6F7...",
      "status": "ACCEPTED", // CREATED | NOT_STARTED | RECEIVED | ACCEPTED | REJECTED | BLOCKED | EXPIRED
      "transactionId": "TXN123456789", // null если оплата ещё не произошла
      "errorCode": null,
      "errorMessage": null,
      "subscriptionQrcId": null // UniQrId подписочного QR, если этот QR — рекуррентное списание (/subscription/pay); иначе null
    }
  ],
  "errorCode":    null,
  "errorMessage": null
}

Статусы QR-кода

POST /api/payments/qr/subscription

Создаёт подписочный QR-код СБП для привязки счёта плательщика. После сканирования плательщик подтверждает привязку в приложении своего банка — шлюз сохраняет данные привязки у себя и переводит подписочный QR в статус ACCEPTED. После этого списания выполняются через /subscription/pay — достаточно передать qrcId подписочного QR и сумму.

Тело запроса

{
  "purpose":        "Ежемесячная подписка",       // описание для плательщика, до 140 символов (опционально)
  "redirectUrl":    "https://example.com/return", // URL возврата после привязки (опционально)
  "ttlMinutes":     1440,                         // время жизни QR в минутах (опционально)
  "imageMediaType": "image/png",                  // формат изображения: "image/png" или "image/svg+xml" (опционально)
  "imageSize":      300                           // размер изображения в пикселях 200–1000 (опционально)
}

Успешный ответ 200 OK

{
  "isSuccess":      true,
  "uniQrId":        "A2B3C4D5E6F7...",    // идентификатор QR в системе банка
  "payload":        "https://qr.nspk.ru/...", // SBP-ссылка для генерации QR
  "status":         "CREATED",
  "imageMediaType": "image/png",           // null если imageMediaType не был передан
  "imageContent":   "iVBORw0KGgo...",     // QR-изображение в base64, null если не запрошено
  "errorCode":      null,
  "errorMessage":   null
}

Флоу привязки счёта

1. Платформа вызывает POST /api/payments/qr/subscription и получает uniQrId и payload.
2. Плательщик сканирует QR в приложении своего банка и подтверждает привязку.
3. Банк отправляет уведомление на URL CallbackSubscriptionUrl с параметрами:

{
  "qrcId":             "A2B3C4D5E6F7...",  // совпадает с uniQrId
  "status":            "ACWP",             // ACWP — привязан, RJCT — отказ
  "subscriptionToken": "TOKEN_VALUE",      // сохраняется шлюзом, платформе не требуется
  "memberId":          "100000012000"      // сохраняется шлюзом, платформе не требуется
}

4. При status: "ACWP" (привязка подтверждена) шлюз переводит подписочный QR в статус ACCEPTED и сохраняет данные привязки (subscriptionToken и memberId) у себя. С этого момента по подписке можно выполнять списания через /subscription/pay.

POST /api/payments/subscription/pay

Выполняет разовое списание с привязанного счёта плательщика (рекуррентный платёж по подписке). Вызывается столько раз, сколько нужно списаний — по одному вызову на каждое.

Предварительно счёт должен быть привязан через подписочный QR: система принимает списание, только если указанный qrcId — это подписочный QR в статусе ACCEPTED (данные привязки subscriptionToken/memberId шлюз подставляет сам). Иначе вернётся ошибка SUBSCRIPTION_NOT_FOUND.

Тело запроса

{
  "qrcId":  "A2B3C4D5E6F7...", // UniQrId ПОДПИСОЧНОГО QR (статус ACCEPTED) (обязательно)
  "amount": 5000               // сумма списания в копейках (обязательно)
}

Успешный ответ 200 OK

{
  "isSuccess":     true,
  "qrcId":         "F9E8D7C6B5A4...", // НОВЫЙ одноразовый QR этого списания — отслеживайте через /qr/status
  "status":        "NOT_STARTED",     // статус нового QR; станет ACCEPTED после зачисления средств
  "transactionId": null,
  "errorCode":     null,
  "errorMessage":  null
}

Ошибка 400 Bad Request

{
  "errorCode":    "SUBSCRIPTION_NOT_FOUND",
  "errorMessage": "Активная подписка не найдена: проверьте qrId (подписочный QR должен быть в статусе ACCEPTED)."
}

GET /api/payments/operation/info

Запрашивает актуальный статус операции у банка по transactionId и обновляет запись в системе.

Query-параметры

Пример запроса

GET {BASE_URL}/api/payments/operation/info?transactionId=TXN123456789
X-Api-Token: ваш_токен_платформы

Успешный ответ 200 OK

{
  "isSuccess":     true,
  "transactionId": "TXN123456789",
  "type":          "C2BQRS",         // тип операции из СБП
  "status":        "ACCEPTED",       // статус операции
  "fpMessageId":   "FP_MSG_ID",      // идентификатор ОПКЦ СБП
  "origSbpId":     null,             // исходный SBP-идентификатор (для возвратов)
  "errorCode":     null,
  "errorMessage":  null
}

POST /api/payments/transfer/rollback

Инициирует автоматический возврат (откат) подписочного перевода по QR-коду. Используется для отмены операции, инициированной через подписку. Статус отслеживается асинхронно через /operation/info.

Тело запроса

{
  "qrcId": "A2B3C4D5E6F7..."  // UniQrId QR-кода (обязательно)
}

Успешный ответ 200 OK

{
  "isSuccess":     true,
  "transactionId": "TXN_ROLLBACK_ID",  // transactionId операции отката
  "errorCode":     null,
  "errorMessage":  null
}

POST /api/payments/payment/refund

Одношаговый возврат платежа по оригинальной транзакции. Инициирует возврат и автоматически подтверждает его в фоне. Фоновый процесс циклически опрашивает статус до получения финального результата.

Тело запроса

{
  "transactionId": "TXN123456789",           // transactionId исходного платежа (обязательно)
  "amount":        5000,                     // сумма возврата в копейках (обязательно)
  "currency":      "RUB",                    // валюта ISO 4217 (обязательно)
  "comment":       "Возврат по запросу клиента" // комментарий (опционально)
}

Успешный ответ 200 OK

{
  "isSuccess":     true,
  "transactionId": "TXN_REFUND_ID",  // transactionId операции возврата
  "errorCode":     null,
  "errorMessage":  null
}