Partner API v1 — документация

← На сайт
Base URL: https://paybeam.ru
Auth: Authorization: Bearer <token>
Content-Type: application/json; charset=utf-8
Rate limit: 60 rpm

Как получить API-токен

1. Зарегистрируйтесь на сайте и войдите в личный кабинет.

2. В ЛК откройте раздел партнёрской программы и оставьте заявку на подключение API.

3. После одобрения заявки откройте раздел API в ЛК и создайте токен для интеграции.

Нужна помощь с подключением: Telegram поддержки — @paybeam_support.

Общие типы и правила

Тип заказа

type: "steam" | "topup" | "voucher"
  • steam — пополнение Steam (сумма задаётся в запросе)
  • topup — пополнение/доставка в аккаунт (без кода)
  • voucher — ваучер/код (код появляется после завершения)

available

available: boolean
Если available=false, заказ по этому сервису/категории/продукту создавать не нужно.

Деньги и проценты

Все суммы в рублях — целые числа: integer.
Проценты комиссий — числа 0..100 (например 1.50).
Округление комиссий в рублях: ceil.

Партнёрская маржа

При создании заказа вы можете передать partner_commission_percent — ваш процент поверх базовой цены Paybeam.
Он влияет на:
  • partner_fee_rub — сколько вы заработаете по заказу
  • amount_pay_rub — сколько платит клиент
Начисление маржи на баланс происходит после завершения заказа.

Поля продукта (fields)

У некоторых продуктов нужно заполнить дополнительные поля. Список полей берите из каталога: product.fields[].
В POST /api/partner/v1/orders передавайте объект fields, где ключи — это fields[].key.
Для topup обычно нужно заполнить все поля из списка (например Input1 и Input2).
Для voucher обязательно передавать email получателя в fields.email.
На этот email будет отправлен код ваучера после завершения заказа. Если вы хотите отправлять код самостоятельно или отображать его только на странице заказа, указывайте свой email вместо email клиента.

1) Services

GET /api/partner/v1/services
Возвращает список сервисов, доступных для создания заказов.

Request

Тело запроса отсутствует. Передавайте заголовок Authorization.
curl -H "Authorization: Bearer <token>" \
  https://paybeam.ru/api/partner/v1/services

Response 200

{
  "services": [
    {
      "code": "steam",
      "name": "Steam",
      "available": true,
      "min_rub": 100,
      "max_rub": 100000,
      "base_commission_percent": 5.00
    }
  ]
}

Ошибки

401 { "error": "unauthorized" }

2) Categories

GET /api/partner/v1/categories
Возвращает категории и подкатегории (без продуктов).
Поле description — русское описание (может быть пустой строкой).

Response 200

{
  "categories": [
    {
      "id": 33,
      "name": "Mobile Legends: Bang Bang",
      "description": "Донат в Mobile Legends (глобальный регион).",
      "available": true,
      "sort": 10,
      "subcategories": [
        {
          "id": 36,
          "name": "Global",
          "description": "Подкатегория для глобального региона.",
          "available": true,
          "sort": 10
        }
      ]
    }
  ]
}

3) Products by category

GET /api/partner/v1/categories/{category_id}/products
Возвращает категорию и список продуктов в ней.
Поля description и help_description — русские тексты (могут быть пустыми строками).

Request

Тело запроса отсутствует.

Response 200

{
  "category": {
    "id": 33,
    "name": "Mobile Legends: Bang Bang",
    "available": true
  },
  "products": [
    {
      "id": 681,
      "category_id": 33,
      "subcategory_id": 36,
      "subcategory_name": "Mobile Legends | Global",
      "name": "156 + 16 алмазов",
      "description": "Пакет алмазов для пополнения.",
      "help_description": "Укажите User ID и Server из профиля игры.",
      "type": "topup",
      "available": true,
      "price_rub": 210,
      "fields": [
        { "key": "Input1", "placeholder": "User ID" },
        { "key": "Input2", "placeholder": "Server" }
      ]
    }
  ]
}
{
  "category": {
    "id": 10,
    "name": "Telegram",
    "available": true
  },
  "products": [
    {
      "id": 555,
      "category_id": 10,
      "subcategory_id": 101,
      "subcategory_name": "Stars",
      "name": "50 звезд",
      "description": "Покупка Stars на указанный аккаунт.",
      "help_description": "Передайте @username получателя.",
      "type": "topup",
      "available": true,
      "price_rub": 10000,
      "fields": [
        {
          "key": "account",
          "placeholder": "@vanya777",
          "description": "Аккаунт Telegram",
          "max_length": 33,
          "validation_rule": "^\\@[A-Za-z0-9_]+$"
        }
      ]
    }
  ]
}

Ошибки

400 { "error": "invalid_category_id" }
404 { "error": "category_not_found" }

4) Product by id

GET /api/partner/v1/products/{product_id}

Response 200

{
  "product": {
    "id": 681,
    "category_id": 33,
    "subcategory_id": 36,
    "subcategory_name": "Mobile Legends | Global",
    "name": "156 + 16 алмазов",
    "description": "Пакет алмазов для пополнения.",
    "help_description": "Укажите User ID и Server из профиля игры.",
    "type": "topup",
    "available": true,
    "price_rub": 210,
    "fields": [
      { "key": "Input1", "placeholder": "User ID" },
      { "key": "Input2", "placeholder": "Server" }
    ]
  }
}

Ошибки

404 { "error": "product_not_found" }

5) Create order (create + pay_url)

POST /api/partner/v1/orders
Создаёт заказ и возвращает ссылку на оплату.
Опционально можно передать redirect_url. После возврата пользователя с оплаты Paybeam сделает редирект на этот URL и добавит параметр order_id (public_id заказа). Если redirect_url не указан — пользователь останется на странице заказа Paybeam.
Правила валидации redirect_url: только абсолютный https:// URL (в prod http:// запрещён), без userinfo (user@host), без scheme-relative (//host), длина ≤ 2048.

5.1 Steam order

Обязательные поля: type, account, amount_pay_rub.
Опционально: partner_commission_percent (по умолчанию 0), redirect_url.
Если проверка Steam-аккаунта включена, невалидный логин вернёт ошибку steam_login_invalid.
{
  "type": "steam",
  "account": "my_steam_login_or_url",
  "amount_pay_rub": 1000,
  "partner_commission_percent": 4.00,
  "redirect_url": "https://partner.example/return"
}

Response 200

{
  "order": {
    "public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24",
    "type": "steam",
    "status": "pending_payment",
    "account": "my_steam_login_or_url",
    "amount_pay_rub": 1000,

    "base_commission_percent": 5.00,
    "partner_commission_percent": 4.00,
    "total_commission_percent": 9.00,

    "partner_fee_rub": 40,
    "credited_rub": 910
  },
  "payment": {
    "pay_url": "https://payment.example/pay?id=..."
  }
}

Формулы (Steam)

partner_fee_rub = ceil(amount_pay_rub * partner_commission_percent / 100)

total_fee_rub = ceil(amount_pay_rub * total_commission_percent / 100)

credited_rub = amount_pay_rub - total_fee_rub

Лимиты Steam (min/max)

Важно: для Steam ограничения min_rub/max_rub из GET /api/partner/v1/servicesприменяются к сумме зачисления credited_rub, а не к сумме оплаты amount_pay_rub.
Условие валидности: min_rub ≤ credited_rub ≤ max_rub.

5.2 Gift order (topup)

Обязательные поля: type, product_id, fields.
fields должен содержать ключи из product.fields[].key. Если у продукта 2 поля — передайте оба.
Опционально: partner_commission_percent (по умолчанию 0), redirect_url.
{
  "type": "topup",
  "product_id": 681,
  "fields": {
    "Input1": "123456789",
    "Input2": "11"
  },
  "partner_commission_percent": 1.50,
  "redirect_url": "https://partner.example/return"
}
Важно: ключи в fields должны соответствовать product.fields[].key из GET /api/partner/v1/products/{id}.

Response 200

{
  "order": {
    "public_id": "11111111-2222-3333-4444-555555555555",
    "type": "topup",
    "status": "pending_payment",
    "product_id": 681,

    "amount_base_rub": 210,
    "partner_commission_percent": 1.50,
    "partner_fee_rub": 4,
    "amount_pay_rub": 214
  },
  "payment": {
    "pay_url": "https://payment.example/qr/?id=..."
  }
}

Формулы (gift)

Важно: для gift-продуктов product.price_rub (и, соответственно, amount_base_rub) считается по модели take-rate, а не как «наценка» 1 + %.
Базовый процент Paybeam для gift зависит от настроек вашего API-токена (или от product.commission_percent как fallback), поэтому в Partner API он уже «вшит» в product.price_rub.
// base price for gift is computed from provider price using take-rate model
    product.price_rub = ceil(provider_price_rub / (1 - base_commission_percent/100))

    amount_base_rub = product.price_rub

    partner_fee_rub = ceil(amount_base_rub * partner_commission_percent / 100)

    amount_pay_rub = amount_base_rub + partner_fee_rub

5.3 Gift order (voucher)

Обязательные поля: type, product_id, fields.email.
После завершения заказа код появится в GET /api/partner/v1/orders/{public_id} как voucher_code.
{
  "type": "voucher",
  "product_id": 777,
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return"
}

6) Order status

GET /api/partner/v1/orders/{public_id}
Возвращает статус заказа. Если type="voucher" и заказ завершён — возвращает voucher_code.
Если статус pending_payment — в ответе также будет объект payment с полем pay_url.
Типичные статусы: pending_payment, payment_received, processing_payout, completed, failed, canceled.

Response 200 (steam, pending_payment)

{
  "order": {
    "public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24",
    "type": "steam",
    "status": "pending_payment",
    "created_at": "2026-01-19T13:10:10Z",

    "account": "my_steam_login_or_url",
    "amount_pay_rub": 1000,

    "base_commission_percent": 5.00,
    "partner_commission_percent": 4.00,
    "total_commission_percent": 9.00,

    "partner_fee_rub": 40,
    "credited_rub": 910
  },
  "payment": {
    "pay_url": "https://payment.example/pay?id=..."
  }
}

Response 200 (voucher, completed)

{
  "order": {
    "public_id": "11111111-2222-3333-4444-555555555555",
    "type": "voucher",
    "status": "completed",
    "created_at": "2026-01-19T13:10:10Z",
    "paid_at": "2026-01-19T13:12:01Z",

    "product_id": 777,
    "amount_base_rub": 5000,
    "partner_commission_percent": 7.50,
    "partner_fee_rub": 375,
    "amount_pay_rub": 5375,

    "voucher_code": "AAAA-BBBB-CCCC"
  }
}

Ошибки

404 { "error": "order_not_found" }

Public order (frontend)

GET /api/orders/public?id={public_id}
Публичный эндпоинт для страницы заказа Paybeam. Возвращает базовую информацию по заказу и (если есть) сохранённую ссылку на оплату.
Поле paymentUrl приходит вместе с заказом только в статусе pending_paymentи может показываться любому пользователю (не только владельцу).

Response 200

{
  "publicId": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24",
  "service": "steam",
  "account": "my_steam_login_or_url",
  "amountRub": 1000,
  "status": "pending_payment",
  "createdAt": "2026-01-19T13:10:10Z",

  "paymentUrl": "https://payment.example/pay?id=..."
}

7) Orders history

GET /api/partner/v1/orders
Возвращает список всех заказов, созданных через Partner API этим партнёром, со всей информацией как в Order status.
Параметры: limit (1..200, по умолчанию 50), offset (≥0).

Response 200

{
  "orders": [
    {
      "public_id": "11111111-2222-3333-4444-555555555555",
      "type": "voucher",
      "status": "completed",
      "created_at": "2026-01-19T13:10:10Z",
      "paid_at": "2026-01-19T13:12:01Z",

      "product_id": 777,
      "amount_base_rub": 5000,
      "partner_commission_percent": 7.50,
      "partner_fee_rub": 375,
      "amount_pay_rub": 5375,

      "voucher_code": "AAAA-BBBB-CCCC"
    },
    {
      "public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24",
      "type": "steam",
      "status": "pending_payment",
      "created_at": "2026-01-19T13:10:10Z",
      "account": "my_steam_login_or_url",
      "amount_pay_rub": 1000,

      "base_commission_percent": 5.00,
      "partner_commission_percent": 4.00,
      "total_commission_percent": 9.00,

      "partner_fee_rub": 40,
      "credited_rub": 910
    }
  ],
  "limit": 50,
  "offset": 0
}

8) Partner balance

GET /api/partner/v1/balance
Возвращает текущий баланс партнёра и историю начислений/списаний.
Начисление партнёрской маржи происходит после завершения заказа (статус completed).
Параметр: limit (1..200, по умолчанию 50) — сколько транзакций вернуть.

Response 200

{
  "balance_rub": 12345,
  "transactions": [
    {
      "id": 10,
      "amount_rub": 40,
      "tx_type": "accrual",
      "created_at": "2026-01-19T13:12:01Z",
      "order_public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24"
    },
    {
      "id": 9,
      "amount_rub": -1000,
      "tx_type": "withdrawal",
      "created_at": "2026-01-18T11:00:00Z"
    }
  ],
  "transactions_limit": 50
}

Ошибки

Коды HTTP: 400, 401, 403, 404, 409, 422, 429, 500.

Формат

{
  "error": "some_error_code",
  "message": "optional human readable"
}

Частые коды ошибок

  • unauthorized — отсутствует/неверный токен
  • forbidden — доступ запрещён
  • invalid_json — некорректный JSON
  • invalid_input — невалидные поля запроса (в т.ч. fields)
  • rate_limited — превышен лимит запросов (HTTP 429)
  • steam_login_invalid — невалидный Steam-логин (если проверка включена)
  • category_not_found, product_not_found, order_not_found
  • product_unavailable — продукт недоступен
  • payment_provider_error — ошибка провайдера оплаты