Payli Partner API

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

Base URL

https://payli.ru

пути ниже указаны полностью, напр. https://payli.ru/api/partner/v1/services

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,
      "pricing": {
        "default_method": "sbp",
        "methods": {
          "sbp":    { "amount_rub": 214.00, "commission_percent": 7.00 },
          "card":   { "amount_rub": 221.00, "commission_percent": 10.00 },
          "crypto": { "amount_rub": 214.00, "amount_usdt": 2.41, "commission_percent": 7.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

цена в рублях (по умолчанию — СБП)

pricing

object

цены по способам оплаты: pricing.methods.{sbp|card|crypto} → amount_rub + commission_percent (crypto также amount_usdt). Способ присутствует, только если доступен. default_method=sbp.

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,
    "pricing": {
      "default_method": "sbp",
      "methods": {
        "sbp":    { "amount_rub": 214.00, "commission_percent": 7.00 },
        "card":   { "amount_rub": 221.00, "commission_percent": 10.00 },
        "crypto": { "amount_rub": 214.00, "amount_usdt": 2.41, "commission_percent": 7.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,
    "pricing": {
      "default_method": "sbp",
      "methods": {
        "sbp":    { "amount_rub": 390.00, "commission_percent": 7.00 },
        "card":   { "amount_rub": 402.00, "commission_percent": 10.00 },
        "crypto": { "amount_rub": 390.00, "amount_usdt": 4.39, "commission_percent": 7.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

payment_method

string

способ оплаты: sbp (синоним acquirer, по умолчанию, СБП) | card | crypto. card — оплата картой (Enot, выше комиссия на надбавку), crypto — оплата криптовалютой

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 для продления, опционально

Способ оплаты (payment_method)

По умолчанию заказ оплачивается ссылкой эквайринга по СБП (acquirer). Карта (card) — оплата банковской картой: тот же рублёвый рельс, что СБП, но с надстройкой к комиссии (карта дороже, покрывает эквайринг). Криптовалюта (crypto) — оплата в USDT. Передайте нужный payment_method в любом типе заказа (Steam / Topup / Voucher / eSIM):card/crypto возвращают payment.pay_url на соответствующую страницу оплаты (для crypto — с выбором монеты/сети и суммойpayment.amount_usdt). Подтверждение приходит обычным вебхуком о статусе заказа. Если способ временно недоступен — 503 с кодом card_unavailable /crypto_unavailable (без молчаливого отката на СБП).

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

Продлить (top-up) eSIM можно только после того, как её текущий пакет закончится — израсходуется трафик или истечёт срок. Пока пакет активен (или выдан, но ещё не использован), создание заказа-продления вернёт 400 renew_not_available с пояснением (остаток трафика / до какой даты действует). Актуальное состояние — в поле esim.packages и esim.renewable_now ответа заказа.

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

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",
    "payment_method": "acquirer",
    "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=..."
  }
}

При payment_method: crypto блок payment содержит сумму в USDT (amount_usdt), а pay_url ведёт на страницу оплаты с выбором монеты и сети:

200 OK · payment_method: crypto

{
  "order": {
    "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
    "type": "voucher",
    "status": "pending_payment",
    "payment_method": "crypto",
    "product_id": 777,
    "amount_pay_rub": 120.00
  },
  "payment": {
    "pay_url": "https://pay.example/crypto/...",
    "amount_usdt": "1.50"
  }
}

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

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",
    "payment_method": "acquirer",
    "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://...",
      "sim_status": "Installed",
      "renewable_now": false,
      "renew_policy": "The package can be renewed after the validity period ends or all the data is consumed.",
      "packages": [
        {
          "name": "eSIM, 1GB, 7 Days, Turkiye, Unthrottled",
          "state": "in_use",
          "status": "Active",
          "initial_data_gb": 1,
          "remaining_gb": 0.4,
          "activated": true,
          "activated_at": "2026-07-11 12:00:00",
          "expires_at": "2026-07-18 12:00:00"
        }
      ]
    }
  }
}

Для eSIM объект esim дополнительно содержит живой статус у поставщика: packages (пакеты с объёмом/остатком/сроком и корзиной state: in_use · assigned · completed · revoked), sim_status, renew_policy и renewable_now — можно ли продлить прямо сейчас. Данные подтягиваются в реальном времени; если поставщик недоступен, поля могут отсутствовать (статус заказа при этом не меняется).

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.
Заказ должен быть оплачен через платёжную ссылку.
Крипто-заказы (payment_method: crypto) через этот эндпоинт не возвращаются — только вручную через поддержку.

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 не передан — заголовок подписи не отправляется.

Ошибки

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

HTTP	error	Когда возникает	Что делать
400	invalid_json	неверный JSON или неизвестное поле	исправить тело запроса
400	invalid_webhook_url	неверный webhook_url	проверить URL
400	invalid_webhook_secret	webhook_secret длиннее 512 символов	сократить секрет
401	unauthorized	неверный токен	проверить Authorization
403	forbidden	операция недоступна	обратиться в поддержку
404	not_found	сущность не найдена	проверить public_id
409	request_in_progress	тот же idempotency_key уже выполняется	повторить после Retry-After
409	idempotency_key_reused_with_different_payload	тот же Idempotency-Key с другими параметрами (сумма/redirect/webhook/TTL)	использовать новый ключ для нового запроса
409	invalid_state	статус не позволяет операцию	проверить статус сущности
400	renew_not_available	продление eSIM запрошено, но текущий тариф ещё НЕ закончился (трафик не израсходован и срок не истёк) — либо истекло 30-дневное окно продления после его окончания	продлить можно только после окончания текущего пакета и в течение 30 дней; проверить esim.packages / esim.renewable_now в статусе заказа
400	renew_not_supported	eSIM не поддерживает продление (тариф/провайдер без top-up)	оформить новую eSIM
400	renew_not_resolvable	не удалось определить eSIM для продления (неверный renew_iccid / renew_order_id)	проверить идентификатор eSIM
409	not_refundable_crypto_order	крипто-оплаченный заказ нельзя вернуть через API	возврат крипты — только вручную через поддержку
409	not_refundable_enot_order	заказ, оплаченный картой (Enot), нельзя вернуть через API	возврат карты — только вручную через поддержку
409	not_refundable_enot_invoice	инвойс, оплаченный картой (Enot), нельзя вернуть через API	возврат карты — только вручную через поддержку
429	rate_limited	превышен лимит	повторить позже
502	payment_url_missing	платёж создан, но провайдер не вернул pay_url	повторить тот же запрос с тем же Idempotency-Key
503	crypto_unavailable	крипто-оплата запрошена, но включённых крипто-провайдеров нет	использовать acquirer/balance или повторить позже
503	card_unavailable	оплата картой запрошена, но card-провайдер недоступен	использовать sbp/acquirer или повторить позже
503	payment_init_recovery_pending	заказ/инвойс создан(а), но pay_url ещё дозаписывается (сбой записи provider_ref)	повторить тот же запрос с тем же Idempotency-Key через пару секунд
503	idempotency_unavailable	временный сбой	повторить позже