Авторизация

Начало работы с OrbitPay API

1. Введение

OrbitPay API позволяет принимать оплату на сайте, в боте или приложении: создать счёт, показать QR или список банков, получить статус и callback.

Все запросы выполняются в формате JSON по протоколу HTTPS.

Базовый URL:

https://pay.orbitpay.su/

Страница оплаты плательщика: https://pay.orbitpay.su/{transactionId}. На компьютере показывается QR СБП, на телефоне — список банков: приложение или веб-версия.

2. Авторизация

В каждый запрос к API передайте ID проекта и API-ключ. ID совпадает с UUID в ссылке личного кабинета и выдаётся при регистрации. Ключ — 24 символа, уникален для каждого аккаунта.

ID и ключ доступны в кабинете: Настройки → Интеграция и API. Полный ключ показывается один раз — при регистрации и после перевыпуска.

Модули CMS

Готовые модули для быстрой интеграции с OrbitPay.

Модули подключаются по запросу в поддержку. REST API доступен сразу после выдачи ключа.

SDK

Для быстрой интеграции используйте SDK для популярных языков.

Создание платежной ссылки без заданного метода

Создаёт счёт и возвращает ссылку на страницу оплаты OrbitPay. На компьютере плательщик сканирует QR СБП, на телефоне выбирает банк — откроется приложение или веб-версия.

ID транзакции генерируется системой автоматически — не передавайте поле id в запросе. Перенаправьте плательщика на url / redirect. Поле qr — ссылка НСПК https://qr.nspk.ru/…, если QR уже готов.

description, payload, return и failedUrl хранятся только на стороне OrbitPay и не передаются во внешний шлюз.

Для отдельных категорий магазинов нужно передавать metadata.userId. Без него антифрод может быть отключён.

Заголовки

Тело запроса

{
  "paymentDetails": {
    "amount": 500,
    "currency": "RUB"
  },
  "description": "Оплата заказа №293",
  "return": "https://shop.example/success",
  "failedUrl": "https://shop.example/fail",
  "payload": "Дополнительная информация",
  "orderId": "order-293",
  "metadata": {
    "userId": "123456789",
    "userName": "@username"
  }
}

Ответ 200

{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "PENDING",
          "url": "https://pay.orbitpay.su/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expiresIn": "00:15:00",
  "rate": 91.2
}

400 — ошибка валидации. 401 — проверьте X-MerchantId / X-Secret.

Создание платежной ссылки с заданным методом

Создаёт транзакцию с заранее выбранным способом оплаты.

Методы оплаты

Тело запроса

{
  "paymentMethod": 2,
  "paymentDetails": {
    "amount": 500,
    "currency": "RUB"
  },
  "description": "Оплата заказа №293",
  "return": "https://shop.example/success",
  "failedUrl": "https://shop.example/fail",
  "payload": "Дополнительная информация",
  "metadata": {
    "userId": "123456789",
    "userName": "@username"
  }
}

Ответ 200

{
  "paymentMethod": "SBPQR",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c463f66afa6",
  "redirect": "https://pay.orbitpay.su/3fa85f64-5717-4562-b3fc-2c463f66afa6",
  "return": "https://shop.example/success",
  "paymentDetails": "500 RUB",
  "status": "PENDING",
  "expiresIn": "00:15:00",
  "merchantId": "1a021d91-9b26-4762-b303-5d4aac74e921",
  "usdtRate": 93.45
}

Получение QR-кода для H2H-транзакции

Возвращает QR СБП в формате НСПК. Тот же QR показывается на странице https://pay.orbitpay.su/{id}.

{
  "amount": 136.12,
  "qr": "https://qr.nspk.ru/AD10006..."
}

Проверка статуса оплаты

Возвращает статус и детали транзакции.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "PENDING",
  "paymentDetails": { "amount": 2000, "currency": "RUB" },
  "merchantName": "Demo Merchant",
  "paymentMethod": "SBPQR",
  "expiresIn": "00:15:00",
  "return": "https://shop.example/success",
  "payload": "custom-payload",
  "description": "Оплата заказа #12345"
}

404 — транзакция не найдена.

Выгрузка транзакций

Выгрузка готовится. Пока сверяйте платежи через GET /transaction/{id} и callback.

{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-09-21T23:59:59Z",
  "status": "CONFIRMED"
}

Получение балансов

Баланс и доступная сумма к выводу отображаются в личном кабинете. Отдельный метод баланса в публичном API появится позже.

[
  { "amount": 15000.5, "currency": "RUB" },
  { "amount": 200, "currency": "USDT", "frozenBalance": 500 }
]

Проверка возможности отмены

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

{
  "supported": true,
  "amountUsdt": 10.89
}

Отмена транзакции

Инициирует возврат средств плательщику. Сначала проверьте возможность через cancel-supported.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "CHARGEBACKED"
}

Вывод на рублёвую карту

Payout API подключается по запросу. После включения в кабинете появится раздел выводов.

Ключ показывается один раз сразу после генерации. Сброс инвалидирует старый ключ.

Подпись запроса (HMAC-SHA256)

Строка для подписи (элементы через \n):

METHOD
PATH
timestamp
idempotency-key
sha256_hex(body)

Подпись: Base64(HMAC-SHA256(SECRET, string_to_sign))

Заголовок: Authorization: OP-HMAC kid={MERCHANT_ID}, ts={timestamp}, sig={подпись}

Допустимая сумма одного вывода: от 1000 до 87500 RUB. Для каждого вывода — новый Idempotency-Key.

{
  "cardNumber": "2200000000000000",
  "amountRub": 1500,
  "payoutMethod": "CARD",
  "currencyRequested": "RUB"
}

Ответ

{
  "withdrawalRecordId": "3c0d321d-40c4-46e3-97f0-7a8f50ce03a6",
  "status": "CREATED",
  "cardMasked": "**** 0000",
  "amountUsdtDebited": 13.270341
}

Пример на Python

import base64, hashlib, hmac, json, time, uuid, requests

MERCHANT_ID = "ваш-merchant-id"
SECRET = "ваш-secret-ключ"
BASE = "https://pay.orbitpay.su"
PATH = "/api/v1/payouts/card-rub"

body = {
    "cardNumber": "2200000000000000",
    "amountRub": 1500,
    "payoutMethod": "CARD",
    "currencyRequested": "RUB",
}
idem_key = str(uuid.uuid4())
body_bytes = json.dumps(body, separators=(",", ":")).encode("utf-8")
ts = int(time.time())
body_hash = hashlib.sha256(body_bytes).hexdigest()
string_to_sign = "\n".join(["POST", PATH, str(ts), idem_key, body_hash])
sig = base64.b64encode(
    hmac.new(SECRET.encode(), string_to_sign.encode(), hashlib.sha256).digest()
).decode()

headers = {
    "Authorization": f"OP-HMAC kid={MERCHANT_ID}, ts={ts}, sig={sig}",
    "Idempotency-Key": idem_key,
    "Content-Type": "application/json",
}
print(requests.post(BASE + PATH, headers=headers, data=body_bytes).text)

Получение сохранённых карт

По умолчанию только активные карты. Передайте onlyActive=false, чтобы получить DISABLED и PENDING.

GET подписывается так же, HMAC. Для тела используется SHA-256 пустой строки.

[
  {
    "cardId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "masked": "•••• •••• •••• 4242",
    "last4": "4242",
    "brand": "МИР",
    "label": "Основная карта",
    "status": "ACTIVE"
  }
]

Callback об изменении статуса

Укажите URL в кабинете: Настройки → Интеграция и API → Callback URL. OrbitPay отправляет JSON, X-MerchantId, X-Orbit-Timestamp и X-Orbit-Signature.

После callback обязательно проверьте статус через GET /transaction/{id} со своими заголовками. Успех — CONFIRMED, отказ — CANCELED, возврат — CHARGEBACKED.

Только HTTPS, публичный IP или домен, валидный SSL. Self-signed, localhost и приватные сети запрещены.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "amount": 1000,
  "currency": "RUB",
  "status": "CONFIRMED",
  "paymentMethod": 2,
  "payload": "custom-payload"
}

Ответьте 200 OK.

Schemas

PaymentStatus

PaymentMethodInt

CreateTransactionRequest

paymentDetails.amount, paymentDetails.currency, description, return, failedUrl. Опционально: payload, orderId, metadata, paymentMethod.

CreateTransactionResponse

transactionId, status, url / redirect (страница https://pay.orbitpay.su/{id}), qr (ссылка НСПК), expiresIn, merchantId.

CallbackPayload

id, amount, currency, status, paymentMethod, payload.

Создать подписку

Рекуррентные СБП-подписки подключаются отдельно. Основной приём — разовый счёт через /transaction/process.

Получить подписку

Возвращает текущий статус и параметры подписки.

Список подписок

Список подписок мерчанта с фильтрами по статусу и дате.

Отменить подписку

Останавливает дальнейшие списания. Уже проведённые платежи не отменяются.

Callback по списанию

Webhook на каждое успешное или неуспешное списание по подписке. Ответьте 200 OK.

Callback по статусу подписки

Webhook при смене статуса подписки: активна, приостановлена, отменена.