Payli|Partner API v1
← На сайт

Partner API

REST API для интеграции каталога Payli в ваш сервис. Все запросы и ответы в JSON.

Base URL
https://payli.ru
Content-Type
application/json; charset=utf-8
Авторизация
Bearer <token>
Rate limit
60 запросов / минута

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

Для доступа к API необходим токен. Порядок получения:

  1. Зарегистрируйтесь на сайте и войдите в личный кабинет.
  2. Откройте раздел партнёрской программы и подайте заявку на подключение API.
  3. После одобрения — откройте раздел API в ЛК и создайте токен.

Передавайте токен в заголовке каждого запроса:

Authorization: Bearer <ваш токен>
Нужна помощь с подключением? Telegram — @payli_support

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

Тип заказа

steam
string
Пополнение Steam — сумма задаётся в запросе
topup
string
Пополнение/доставка в аккаунт (без кода)
voucher
string
Ваучер/код — код приходит после завершения
esim
string
eSIM — LPA-код для активации приходит после завершения

available

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

service

"steam" или "gift" — внутренний код сервиса. Присутствует в каждом ответе с заказом.

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

Все суммы в рублях — числа с двумя знаками: 1234.56

Проценты — числа 0…100: 1.50

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

При создании заказа можно передать partner_commission_percent — ваш процент поверх базовой цены Payli. Влияет на:

  • partner_fee_rub — сколько вы заработаете
  • amount_pay_rub — сколько платит клиент

Начисление маржи на баланс — после завершения заказа.

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

У продуктов могут быть доп. поля. Список — в product.fields[] из каталога.

В POST /api/partner/v1/orders передавайте fields, где ключи — fields[].key.

Для topup заполните все поля (Input1, Input2…). Для voucher обязательно fields.email — на него придёт код. Для esim обязательно fields.email — на него придёт LPA-код и QR.

GETServices

GET/api/partner/v1/services

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

Response 200 OK

Response
{
  "services": [
    {
      "code": "steam",
      "name": "Steam",
      "available": true,
      "min_rub": 100.00,
      "max_rub": 100000.00,
      "base_commission_percent": 5.00
    }
  ]
}

Errors

401 { "error": "unauthorized" }

GETCategories

GET/api/partner/v1/categories

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

Response 200 OK

Response
{
  "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
        }
      ]
    }
  ]
}

GETProducts by category

GET/api/partner/v1/categories/{category_id}/products

Возвращает категорию и список продуктов.

description и help_description — русские тексты (могут быть пустыми).

Response 200 OK

Topup product
{
  "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.00,
      "fields": [
        { "key": "Input1", "placeholder": "User ID" },
        { "key": "Input2", "placeholder": "Server" }
      ]
    }
  ]
}
Voucher product
{
  "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.00,
      "fields": [
        {
          "key": "account",
          "placeholder": "@vanya777",
          "description": "Аккаунт Telegram",
          "max_length": 33,
          "validation_rule": "^\\@[A-Za-z0-9_]+$"
        }
      ]
    }
  ]
}

Errors

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

GETProduct by id

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

Response 200 OK

Response
{
  "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.00,
    "fields": [
      { "key": "Input1", "placeholder": "User ID" },
      { "key": "Input2", "placeholder": "Server" }
    ]
  }
}

Errors

404 { "error": "product_not_found" }

POSTCreate order

POST/api/partner/v1/orders

Создаёт заказ и возвращает ссылку на оплату.

redirect_url — после оплаты Payli редиректит на этот URL с параметром order_id. Только https://, без userinfo, длина ≤ 2048. Если не указан — пользователь останется на странице заказа Payli.

5.1 Steam order

typereq
"steam"
Тип заказа
accountreq
string
Steam логин или URL профиля
amount_pay_rubreq
number
Сумма оплаты в рублях
partner_commission_percent
number
Ваш процент (по умолчанию 0)
redirect_url
string
URL для возврата после оплаты
Request
{
  "type": "steam",
  "account": "my_steam_login_or_url",
  "amount_pay_rub": 1000.00,
  "partner_commission_percent": 4.00,
  "redirect_url": "https://partner.example/return"
}
Response 200
{
  "order": {
    "public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24",
    "type": "steam",
    "service": "steam",
    "status": "pending_payment",
    "account": "my_steam_login_or_url",
    "amount_pay_rub": 1000.00,

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

    "partner_commission_rub": 40.00,
    "partner_fee_rub": 40.00,
    "credited_rub": 910.00
  },
  "payment": {
    "pay_url": "https://payment.example/pay?id=..."
  }
}

Формулы (Steam)

partner_commission_rub = round(amount_pay_rub × partner_commission_percent / 100, 2)
partner_fee_rub       = partner_commission_rub
total_fee_rub         = round(amount_pay_rub × total_commission_percent / 100, 2)
credited_rub          = amount_pay_rub − total_fee_rub
Лимиты Steam: min/max из GET /api/partner/v1/services применяются к credited_rub, а не к amount_pay_rub. Условие: min_rub ≤ credited_rub ≤ max_rub.

5.2 Gift order (topup)

typereq
"topup"
Тип заказа
product_idreq
number
ID продукта из каталога
fieldsreq
object
Ключи из product.fields[].key
partner_commission_percent
number
Ваш процент (по умолчанию 0)
redirect_url
string
URL для возврата после оплаты
Request
{
  "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",
    "service": "gift",
    "status": "pending_payment",
    "product_id": 681,
    "product_name": "156 + 16 алмазов",
    "category_name": "Mobile Legends: Bang Bang",
    "subcategory_name": "Global",

    "amount_base_rub": 210.00,
    "partner_commission_percent": 1.50,
    "partner_commission_rub": 3.15,
    "partner_fee_rub": 3.15,
    "amount_pay_rub": 214.00
  },
  "payment": {
    "pay_url": "https://payment.example/qr/?id=..."
  }
}

Формулы (gift)

Для gift-продуктов product.price_rub считается по модели take-rate, а не как наценка. Базовый % Payli уже «вшит» в price_rub.
product.price_rub    = round(provider_price / (1 − base_commission_percent/100), 2)
amount_base_rub      = product.price_rub
partner_commission   = round(amount_base_rub × partner_commission_percent / 100, 2)
partner_fee_rub      = partner_commission_rub
amount_pay_rub       = amount_base_rub + partner_fee_rub

5.3 Gift order (voucher)

typereq
"voucher"
Тип заказа
product_idreq
number
ID продукта из каталога
fields.emailreq
string
Email для получения кода ваучера
partner_commission_percent
number
Ваш процент (по умолчанию 0)
redirect_url
string
URL для возврата после оплаты
Request
{
  "type": "voucher",
  "product_id": 777,
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return"
}

После завершения код появится в GET /api/partner/v1/orders/{public_id} как voucher_code.

5.4 Gift order (eSIM)

typereq
"esim"
Тип заказа
product_idreq
number
ID продукта из каталога
fields.emailreq
string
Email для получения LPA-кода и QR
partner_commission_percent
number
Ваш процент (по умолчанию 0)
redirect_url
string
URL для возврата после оплаты
Request
{
  "type": "esim",
  "product_id": 1042,
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return"
}

После завершения LPA-код появится в GET /api/partner/v1/orders/{public_id} как esim_code. На указанный email автоматически отправляется письмо с кодом и QR.

esim_code — строка формата LPA (напр. LPA:1$example.com$XXXXXX). Из неё можно сгенерировать QR-код для установки eSIM на устройство.

GETOrder status

GET/api/partner/v1/orders/{public_id}

Возвращает статус заказа. Для voucher-заказа в статусе completed — возвращает voucher_code. Для esim-заказа — esim_code (LPA-строка).

Если статус pending_payment — в ответе будет объект payment.pay_url.

Статусы

pending_paymentpayment_receivedprocessing_payoutcompletedfailedcanceledrefundedcreation_failed

Response 200 OK (steam, pending_payment)

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

    "account": "my_steam_login_or_url",
    "amount_pay_rub": 1000.00,

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

    "partner_commission_rub": 40.00,
    "partner_fee_rub": 40.00,
    "credited_rub": 910.00
  },
  "payment": {
    "pay_url": "https://payment.example/pay?id=..."
  }
}

Response 200 OK (voucher, completed)

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

    "product_id": 777,
    "product_name": "Premium на 3 месяца",
    "category_name": "Telegram",
    "subcategory_name": "Premium",
    "amount_base_rub": 5000.00,
    "partner_commission_percent": 7.50,
    "partner_commission_rub": 375.00,
    "partner_fee_rub": 375.00,
    "amount_pay_rub": 5375.00,

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

Response 200 OK (esim, completed)

eSIM order
{
  "order": {
    "public_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "type": "esim",
    "service": "gift",
    "status": "completed",
    "created_at": "2026-04-17T10:00:00Z",
    "paid_at": "2026-04-17T10:01:30Z",

    "product_id": 1042,
    "product_name": "Europe 10GB / 30 days",
    "category_name": "eSIM",
    "subcategory_name": "Europe",
    "amount_base_rub": 2500.00,
    "partner_commission_percent": 2.00,
    "partner_commission_rub": 50.00,
    "partner_fee_rub": 50.00,
    "amount_pay_rub": 2550.00,

    "esim_code": "LPA:1$rsp.example.com$ABCDEF123456"
  }
}

Errors

404 { "error": "order_not_found" }

GETPublic order (frontend)

GET/api/orders/public?id={public_id}

Публичный эндпоинт для страницы заказа Payli. Возвращает базовую инфо и ссылку на оплату.

paymentUrl приходит только в статусе pending_payment.

Response 200 OK

Response
{
  "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=..."
}

GETOrders history

GET/api/partner/v1/orders

Список всех заказов, созданных через Partner API.

limit
number
1…200, по умолчанию 50
offset
number
≥ 0

Response 200 OK

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

      "product_id": 777,
      "product_name": "Premium на 3 месяца",
      "category_name": "Telegram",
      "subcategory_name": "Premium",
      "amount_base_rub": 5000.00,
      "partner_commission_percent": 7.50,
      "partner_commission_rub": 375.00,
      "partner_fee_rub": 375.00,
      "amount_pay_rub": 5375.00,

      "voucher_code": "AAAA-BBBB-CCCC"
    },
    {
      "public_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "type": "esim",
      "service": "gift",
      "status": "completed",
      "created_at": "2026-04-17T10:00:00Z",
      "paid_at": "2026-04-17T10:01:30Z",

      "product_id": 1042,
      "product_name": "Europe 10GB / 30 days",
      "category_name": "eSIM",
      "subcategory_name": "Europe",
      "amount_base_rub": 2500.00,
      "partner_commission_percent": 2.00,
      "partner_commission_rub": 50.00,
      "partner_fee_rub": 50.00,
      "amount_pay_rub": 2550.00,

      "esim_code": "LPA:1$rsp.example.com$ABCDEF123456"
    },
    {
      "public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24",
      "type": "steam",
      "service": "steam",
      "status": "pending_payment",
      "created_at": "2026-01-19T13:10:10Z",
      "account": "my_steam_login_or_url",
      "amount_pay_rub": 1000.00,

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

      "partner_commission_rub": 40.00,
      "partner_fee_rub": 40.00,
      "credited_rub": 910.00
    }
  ],
  "limit": 50,
  "offset": 0
}

GETPartner balance

GET/api/partner/v1/balance

Текущий баланс и история начислений / списаний. Маржа начисляется после completed.

limit
number
1…200, по умолчанию 50

Response 200 OK

Response
{
  "balance_rub": 123.45,
  "transactions": [
    {
      "id": 10,
      "amount_rub": 40.00,
      "tx_type": "accrual",
      "created_at": "2026-01-19T13:12:01Z",
      "order_public_id": "b0c2c1b2-38a1-4be7-9c28-9f4c8a6f6c24"
    },
    {
      "id": 9,
      "amount_rub": -1000.00,
      "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Невалидные поля запроса
rate_limitedПревышен лимит запросов (429)
steam_login_invalidНевалидный Steam-логин
category_not_foundКатегория не найдена
product_not_foundПродукт не найден
order_not_foundЗаказ не найден
product_unavailableПродукт недоступен
payment_provider_errorОшибка провайдера оплаты