Payli|Partner API
← На сайт

Payli Partner API

REST API для получения каталога, создания заказов, отслеживания статусов, получения результата, проверки баланса и возврата заказов.

Base path
/api/partner/v1
Content-Type
application/json
Авторизация
Authorization: Bearer <API_TOKEN>
Лимиты
GET — 600 / мин · POST — 60 / мин

Авторизация

Все запросы выполняются с API-токеном.

Authorization: Bearer <API_TOKEN>

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

  • Заголовок запроса: Content-Type: application/json.
  • Все суммы передаются и возвращаются в рублях: 100.00.
  • Все даты возвращаются в формате RFC3339: 2026-05-06T09:31:09Z.
  • Неизвестные поля в POST-запросах не допускаются. Если передать поле, которого нет в документации, API вернёт ошибку.
  • Для безопасных повторов POST /orders используйте idempotency_key.

GETКаталог · Services

Список доступных сервисов каталога.

GET/api/partner/v1/services
Response
{
  "services": [
    {
      "code": "steam",
      "name": "Steam",
      "available": true,
      "min_rub": 100.00,
      "max_rub": 15000.00,
      "base_commission_percent": 4.00
    }
  ]
}
code
string
код сервиса
name
string
название
available
boolean
доступен ли сервис
min_rub
number
минимальная сумма (для Steam)
max_rub
number
максимальная сумма (для Steam)
base_commission_percent
number
базовая комиссия

GETКаталог · Categories

Список категорий с подкатегориями.

GET/api/partner/v1/categories
Response
{
  "categories": [
    {
      "id": 33,
      "name": "Mobile Legends",
      "description": "Пополнение Mobile Legends",
      "available": true,
      "sort": 100,
      "subcategories": [
        {
          "id": 36,
          "name": "Global",
          "description": "",
          "available": true,
          "sort": 100
        }
      ]
    }
  ]
}
id
number
ID категории
name
string
название
description
string
описание
available
boolean
доступна ли категория
sort
number
порядок сортировки
subcategories
array
подкатегории (id, name, description, available, sort)

GETКаталог · Products by category

Товары выбранной категории.

GET/api/partner/v1/categories/{category_id}/products
Response
{
  "category": {
    "id": 33,
    "name": "Mobile Legends",
    "available": true
  },
  "products": [
    {
      "id": 681,
      "category_id": 33,
      "subcategory_id": 36,
      "subcategory_name": "Global",
      "name": "156 + 16 алмазов",
      "description": "Пакет алмазов",
      "help_description": "Укажите User ID и Server",
      "type": "topup",
      "available": true,
      "price_rub": 214.00,
      "fields": [
        {
          "key": "Input1",
          "placeholder": "User ID"
        }
      ]
    }
  ]
}
id
number
ID товара (для product_id в заказе)
category_id / subcategory_id
number
категория и подкатегория
subcategory_name
string
название подкатегории
name / description / help_description
string
названия и подсказки
type
string
тип: topup, voucher, esim
available
boolean
доступен ли товар
price_rub
number
цена в рублях
fields
array
обязательные поля (key, placeholder) для fields в заказе

GETКаталог · Product by id

Один товар по идентификатору.

GET/api/partner/v1/products/{product_id}
Response
{
  "product": {
    "id": 681,
    "category_id": 33,
    "subcategory_id": 36,
    "subcategory_name": "Global",
    "name": "156 + 16 алмазов",
    "description": "Пакет алмазов",
    "help_description": "Укажите User ID и Server",
    "type": "topup",
    "available": true,
    "price_rub": 214.00,
    "fields": [
      {
        "key": "Input1",
        "placeholder": "User ID"
      }
    ]
  }
}

Товар eSIM содержит дополнительный объект esim:

Response · eSIM
{
  "product": {
    "id": 1042,
    "category_id": 50,
    "subcategory_id": 51,
    "subcategory_name": "Европа",
    "name": "Европа · 10 ГБ · 30 дней",
    "type": "esim",
    "available": true,
    "price_rub": 390.00,
    "fields": [],
    "esim": {
      "country_code": "EU",
      "geo_scope": "region",
      "package_type": "data",
      "data_unit": "GB",
      "data_qty": 10,
      "data_unlimited": false,
      "validity_days": 30,
      "voice_minutes": 0,
      "voice_unlimited": false,
      "sms": 0,
      "sms_unlimited": false,
      "sms_incoming_only": false,
      "operator": "Orange",
      "max_generation": "5G",
      "can_renew": true,
      "coverage_count": 39,
      "coverage_country_codes": ["FR", "DE", "IT", "ES"]
    }
  }
}

POSTСоздание заказа

POST/api/partner/v1/orders

Создаёт заказ и возвращает ссылку на оплату. После оплаты статус заказа можно получить через GET /api/partner/v1/orders/{public_id}.

Поля

typereq
string
тип заказа: steam, topup, voucher, esim
account
string
аккаунт получателя, только для Steam
amount_pay_rub
number
сумма заказа, только для Steam
product_id
number
ID товара, только для topup / voucher / eSIM
fields
object
поля товара, только для topup / voucher / eSIM
partner_commission_percent
number
партнёрская наценка, опционально
redirect_url
string
URL возврата после оплаты, опционально
webhook_url
string
URL для уведомлений по заказу, опционально
webhook_secret
string
секрет для подписи webhook, опционально (≤512 символов)
idempotency_key
string
ключ идемпотентности, опционально (≤128 символов)
renew_order_id
string
public_id исходного eSIM-заказа для продления, опционально
renew_iccid
string
ICCID eSIM для продления, опционально

Steam

POST /api/partner/v1/orders
{
  "type": "steam",
  "account": "my_steam_login_or_url",
  "amount_pay_rub": 1000.00,
  "partner_commission_percent": 4.00,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10001"
}

Topup

POST /api/partner/v1/orders
{
  "type": "topup",
  "product_id": 681,
  "fields": {
    "Input1": "123456789",
    "Input2": "11"
  },
  "partner_commission_percent": 1.50,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10002"
}

Voucher

POST /api/partner/v1/orders
{
  "type": "voucher",
  "product_id": 777,
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10003"
}

Voucher без email:

POST /api/partner/v1/orders
{
  "type": "voucher",
  "product_id": 777,
  "fields": {
    "email": ""
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10004"
}

eSIM

POST /api/partner/v1/orders
{
  "type": "esim",
  "product_id": 1042,
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10005"
}

Продление eSIM

По исходному заказу:

POST /api/partner/v1/orders
{
  "type": "esim",
  "renew_order_id": "5f44b1b0-2f8d-45a9-82f5-4b0a26cda111",
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10006"
}

По ICCID:

POST /api/partner/v1/orders
{
  "type": "esim",
  "renew_iccid": "8943108170000000000",
  "product_id": 1042,
  "fields": {
    "email": "customer@example.com"
  },
  "partner_commission_percent": 2.00,
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10007"
}

Ответ

200 OK
{
  "order": {
    "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
    "type": "voucher",
    "status": "pending_payment",
    "product_id": 777,
    "amount_base_rub": 117.65,
    "partner_commission_percent": 2.00,
    "partner_commission_rub": 2.35,
    "partner_fee_rub": 2.35,
    "amount_pay_rub": 120.00
  },
  "payment": {
    "pay_url": "https://payment.example/pay?id=..."
  }
}

Статусы заказов

pending_payment
status
ожидает оплаты
payment_received
status
оплата получена
processing_payout
status
идёт выдача
completed
status
завершён
failed
status
ошибка выдачи
canceled
status
отменён
refunded
status
возвращён
chargeback
status
спор / возврат от плательщика
creation_failed
status
не удалось создать оплату

GETПолучение заказа

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

Возвращает заказ: статус, суммы и результат выдачи. Код ваучера (voucher_code) и данные eSIM (esim_code, esim) появляются после статуса completed.

pending_payment:

Response
{
  "order": {
    "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
    "type": "voucher",
    "status": "pending_payment",
    "product_id": 777,
    "amount_pay_rub": 120.00,
    "created_at": "2026-05-06T09:31:00Z"
  },
  "payment": {
    "pay_url": "https://payment.example/pay?id=..."
  }
}

completed · voucher:

Response
{
  "order": {
    "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
    "type": "voucher",
    "status": "completed",
    "product_id": 777,
    "amount_pay_rub": 120.00,
    "voucher_code": "ABCD-EFGH-IJKL",
    "created_at": "2026-05-06T09:31:00Z",
    "paid_at": "2026-05-06T09:31:09Z"
  }
}

completed · eSIM:

Response
{
  "order": {
    "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
    "type": "esim",
    "status": "completed",
    "product_id": 1042,
    "amount_pay_rub": 390.00,
    "esim_code": "LPA:1$consumer.rsp.world$XXXX",
    "esim": {
      "qr_code": "LPA:1$consumer.rsp.world$XXXX",
      "smdp_address": "consumer.rsp.world",
      "matching_id": "XXXX",
      "iccid": "8943108170000000000",
      "can_renew": true,
      "apple_link": "https://...",
      "android_link": "https://..."
    }
  }
}

GETСписок заказов

GET/api/partner/v1/orders

Список заказов партнёра. Параметры: limit (по умолчанию 50, макс 200), offset.

Response
{
  "orders": [
    {
      "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
      "type": "voucher",
      "status": "completed",
      "product_id": 777,
      "amount_pay_rub": 120.00,
      "created_at": "2026-05-06T09:31:00Z",
      "paid_at": "2026-05-06T09:31:09Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

POSTRefund order

POST/api/partner/v1/orders/{public_id}/refund

Возвращает оплату по заказу, который был оплачен через платёжную ссылку и завершился ошибкой выдачи.

Условия

  • Заказ должен принадлежать партнёру.
  • Заказ должен быть в статусе failed.
  • Заказ должен быть оплачен через платёжную ссылку.
Request
{
  "reason": "manual_refund"
}
Response
{
  "order": {
    "public_id": "5f44b1b0-2f8d-45a9-82f5-4b0a26cda111",
    "status": "refunded"
  },
  "fee": {
    "rub": 30.00,
    "percent": 3.00
  }
}

GETБаланс

GET/api/partner/v1/balance

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

Response
{
  "balance_rub": 1520.45,
  "transactions": [
    {
      "id": 1912,
      "amount_rub": -97.50,
      "tx_type": "order_debit",
      "order_public_id": "7a85c2c1-3e9f-4ba2-91g6-5c1b27deb222",
      "created_at": "2026-05-06T09:12:44Z"
    }
  ],
  "transactions_limit": 50
}

Типы операций (tx_type)

invoice_topup
tx_type
пополнение баланса
invoice_refund
tx_type
списание при возврате пополнения
invoice_chargeback
tx_type
удержание по chargeback
invoice_chargeback_release
tx_type
снятие удержания
order_debit
tx_type
списание по заказу
order_debit_refund
tx_type
возврат списания по заказу
order_refund_fee
tx_type
комиссия при возврате заказа
accrual
tx_type
начисление
withdrawal
tx_type
вывод средств
adjustment
tx_type
корректировка

Webhooks

Если в запросе создания заказа передан webhook_url, Payli будет отправлять POST-уведомления при изменении статуса заказа.

Параметры (в POST /orders)

webhook_url
string
URL для уведомлений по заказу
webhook_secret
string
секрет для HMAC-подписи

Payload

{
  "event": "order.status",
  "entity": "order",
  "public_id": "f80d95fb-2888-4108-8b6c-79704eb09b92",
  "order_public_id": "f80d95fb-2888-4108-8b6c-79704eb09b92",
  "status": "completed",
  "amount_rub": 500.00,
  "attempt": 1,
  "ts": "2026-05-21T07:09:43Z"
}

amount_rub — в рублях, число с 2 знаками (например 500.00), не в копейках.

Headers

Content-Type: application/json
X-Payli-Event-Id: 12345
X-Payli-Signature: sha256=<hmac>

Подпись

X-Payli-Signature = sha256=<HMAC-SHA256(raw_body, webhook_secret)>. Если webhook_secret не передан — заголовок подписи не отправляется.

Гарантии доставки

  • Терминальные статусы гарантированы (completed, failed, refunded, chargeback) — доставляются с ретраями.
  • Промежуточный payment_received — best-effort (может не прийти при быстром переходе в терминальный статус). Ориентируйтесь на терминальные статусы.
  • Дедуплицируйте по X-Payli-Event-Id (возможны повторы при ретраях).

Ошибки

Ошибки возвращаются в JSON: { "error": "<code>", "message": "<optional>" }.

HTTPerrorКогда возникаетЧто делать
400invalid_jsonневерный JSON или неизвестное полеисправить тело запроса
400invalid_webhook_urlневерный webhook_urlпроверить URL
400invalid_webhook_secretwebhook_secret длиннее 512 символовсократить секрет
401unauthorizedневерный токенпроверить Authorization
403forbiddenоперация недоступнаобратиться в поддержку
404not_foundсущность не найденапроверить public_id
409request_in_progressтот же idempotency_key уже выполняетсяповторить после Retry-After
409idempotency_key_reused_with_different_payloadтот же Idempotency-Key с другими параметрами (сумма/redirect/webhook/TTL)использовать новый ключ для нового запроса
409invalid_stateстатус не позволяет операциюпроверить статус сущности
429rate_limitedпревышен лимитповторить позже
503fee_config_unavailableвременный сбой при чтении тарифа (создание инвойса)повторить позже
503payment_init_recovery_pendingзаказ/инвойс создан(а), но pay_url ещё дозаписывается (сбой записи provider_ref)повторить тот же запрос с тем же Idempotency-Key через пару секунд
503idempotency_unavailableвременный сбойповторить позже