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>

Права токена (scopes)

Чтение (каталог, заказы, баланс, переписка) доступно любому действующему токену. Действия требуют прав, которые выдаются токену при создании; без нужного права — 403 insufficient_scope или 403 forbidden.

orders_create_acquirer

scope

POST /orders с оплатой ссылкой (sbp, card, crypto); POST-действия в чате ручного заказа

orders_refund

scope

POST /orders/{public_id}/refund

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

Заголовок запроса: Content-Type: application/json.
Все суммы передаются и возвращаются в рублях: 100.00.
Все даты возвращаются в формате RFC3339: 2026-05-06T09:31:09Z.
Неизвестные поля в теле POST /orders не допускаются — 400 invalid_json. В остальных POST (чат, подтверждение, спор) лишние поля игнорируются.
Для безопасных повторов POST /orders передавайте idempotency_key (или заголовок Idempotency-Key): повтор с тем же ключом вернёт уже созданный заказ с флагом idempotent_replay: true; тело повторного запроса не сверяется — ключ должен быть уникальным на каждый отдельный заказ.

GETКаталог · Сервисы

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

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 / max_rub

number

Steam: границы суммы, зачисляемой на аккаунт (credited_rub — amount_pay_rub за вычетом комиссии); вне границ — 422 invalid_amount

base_commission_percent

number

базовая комиссия

GETКаталог · Категории

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

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Каталог · Товары категории

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

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, manual (ручная выдача исполнителем — заказ идёт через чат)

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, description, max_length, validation_rule, values (допустимые значения), sensitive

Поле с sensitive: true — это учётные данные покупателя (пароль или токен от аккаунта). Вводите его скрытым полем и не показывайте покупателю повторно. В ответах API поля заказа возвращаются в том виде, в котором вы их прислали, включая значения sensitive-полей — храните их как секрет.

GETКаталог · Товар по 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, manual (ручная выдача, см. раздел ниже)

account

string

аккаунт получателя, только для Steam

amount_pay_rub

number

сумма заказа, только для Steam

product_id

number

ID товара — для topup / voucher / eSIM / manual (при продлении eSIM по renew_order_id можно не передавать)

fields

object

поля товара из его карточки — для topup / voucher / eSIM / manual; у voucher / eSIM поле email необязательно (пусто — без письма покупателю; непустое должно быть валидным адресом)

payment_method

string

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

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 / manual):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"
  }
}

Неоплаченный заказ отменяется через 30 минут (canceled), но отмена не останавливает уже отправленную on-chain транзакцию: если оплата придёт позже, заказ автоматически вернётся в payment_received и уйдёт в выдачу (вебхук order.status).

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

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

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

pending_payment · sbp:

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

pending_payment · crypto:

Response

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

completed · voucher:

Response

{
  "order": {
    "public_id": "8af8e6b2-19f1-48d1-9e3e-67e9e8c0a814",
    "type": "voucher",
    "status": "completed",
    "product_id": 777,
    "amount_pay_rub": 120.00,
    "account": "player@example.com",
    "fields": {
      "login": "player@example.com",
      "server": "eu-west"
    },
    "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"
        }
      ]
    }
  }
}

Заказ отдаётся вместе с данными, с которыми он был создан: account — аккаунт получателя, fields — поля товара в том виде, в котором вы их прислали. Причина неуспеха в ответе не передаётся: если заказ закончился ошибкой, напишите нам с его public_id — разберём.

Для 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
}

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

pending_payment

status

ожидает оплаты

payment_received

status

оплата получена

processing_payout

status

идёт выдача

awaiting_confirmation

status

только manual: исполнитель выдал, ждём подтверждения покупателя (без ответа — авто через ~30 мин)

dispute

status

только manual: покупатель открыл спор по выдаче; чат продолжается, автоподтверждение не срабатывает

completed

status

выдан

failed

status

ошибка выдачи (оплата получена, товар не выдан)

canceled

status

отменён: не оплачен в срок либо оплата с баланса возвращена после ошибки выдачи

refunded

status

оплата возвращена покупателю

chargeback

status

платёж оспорен плательщиком в банке; к спору в чате ручного заказа не относится

creation_failed

status

не удалось создать оплату

Конечные статусы: completed, failed, canceled, refunded, chargeback, creation_failed — выдача закончена (после completed возможен только переход в refunded / chargeback). Остальные — заказ в работе: ждите вебхук или опрашивайте.

Ручная выдача (type: manual)

Часть товаров выдаёт исполнитель вручную: подписки с активацией на аккаунте, готовые аккаунты, покупки в сторонних магазинах. В каталоге у таких товаров type: "manual". После оплаты по заказу открывается чат с исполнителем: он уточняет данные (логин, код из письма), сообщает о выдаче, а покупатель подтверждает получение или открывает спор. Через API доступны все действия покупателя: чтение и отправка сообщений, подтверждение, открытие и снятие спора. Пишет ли ваш покупатель через ваш интерфейс или вы от его имени — для исполнителя это один участник чата (client).

Как это идёт по шагам

POST /orders с type: "manual" — как обычный заказ. В fields передайте поля из карточки товара (fields в GET /products/{product_id}); чаще всего это только email покупателя.
После оплаты заказ переходит в processing_payout и передаётся исполнителю — с этого момента работает GET …/messages. До оплаты он отвечает 409 chat_not_ready.
Исполнитель пишет в чат. О каждом его сообщении (и о служебных сообщениях чата) приходит вебхук order.message, если задан webhook_url; ответы отправляйте через POST …/messages. Можно и просто опрашивать GET …/messages — не чаще раза в 5 секунд на заказ.
Исполнитель отметил выдачу → статус awaiting_confirmation (вебхук order.status). Дальше три пути: POST …/confirm — заказ завершается; POST …/dispute — статус dispute, диалог продолжается; без ответа заказ подтверждается автоматически примерно через 30 минут.
В споре: POST …/confirm — вопрос решён, заказ завершается; POST …/dispute/withdraw — спор снят, заказ снова в awaiting_confirmation (повторный вебхук этого статуса не приходит — статус есть в ответе запроса и в GET /orders/{public_id}). Если спор решён в пользу исполнителя, заказ завершается completed без вашего подтверждения.
Спор решён в пользу покупателя или исполнитель отменил заказ на любом этапе → failed (вебхук). Деньги автоматически не возвращаются: оплату по СБП верните через POST …/refund (см. «Возврат заказа»), для карты и криптовалюты — через поддержку.

Результат выдачи (данные аккаунта, код, скриншот) приходит текстом в чат — отдельного поля voucher_code у ручных заказов нет. Обычно выдача занимает 5–15 минут, если покупатель отвечает исполнителю; ориентируйтесь на статусы, а не на время.

Задержки. Состояние у исполнителя и новые сообщения сверяются раз в минуту, поэтому статусы awaiting_confirmation / dispute / completed, поле manual_state, флаги chat.can_* и вебхуки могут отставать до минуты. Ваши собственные действия (confirm / dispute / withdraw) отражаются в статусе сразу. GET …/messages отдаёт переписку и состояние напрямую от исполнителя.

Создание ручного заказа

POST /api/partner/v1/orders

{
  "type": "manual",
  "product_id": 12034,
  "fields": { "email": "buyer@example.com" },
  "payment_method": "sbp",
  "redirect_url": "https://partner.example/return",
  "webhook_url": "https://partner.example/payli/webhook",
  "webhook_secret": "your-random-secret",
  "idempotency_key": "order-10008"
}

Ответ — как у остальных заказов: order со статусом pending_payment и payment.pay_url. После оплаты заказ уходит исполнителю. Если у товара есть обязательные поля, а вы их не прислали — 400 invalid_input с перечнем ожидаемых ключей. В account заказа попадает первое несекретное поле из fields (обычно email).

Чтение ручного заказа

GET /orders/{public_id} для ручного заказа дополнительно отдаёт manual_state и блок chat.

Response

{
  "order": {
    "public_id": "f80d95fb-2888-4108-8b6c-79704eb09b92",
    "type": "manual",
    "service": "xbox",
    "status": "awaiting_confirmation",
    "payment_method": "acquirer",
    "created_at": "2026-09-12T09:58:00Z",
    "paid_at": "2026-09-12T09:59:30Z",
    "manual_state": "fulfilled",
    "chat": {
      "available": true,
      "can_confirm": true,
      "can_dispute": true,
      "can_withdraw": false,
      "messages_url": "/api/partner/v1/orders/f80d95fb-2888-4108-8b6c-79704eb09b92/messages",
      "auto_confirm_in": "около 30 минут после выдачи, если покупатель не подтвердил и не открыл спор"
    },
    "product_id": 12034,
    "product_name": "Xbox Game Pass Ultimate — 1 месяц · активация на аккаунте",
    "account": "buyer@example.com",
    "fields": { "email": "buyer@example.com" },
    "amount_base_rub": 1290.00,
    "partner_commission_percent": 0.00,
    "partner_commission_rub": 0.00,
    "partner_fee_rub": 0.00,
    "amount_pay_rub": 1290.00
  }
}

manual_state

string

состояние у исполнителя: created · processing · waiting_customer (ждёт ответа в чате) · fulfilled (выдано) · dispute · completed · cancelled. Пустая строка — до оплаты и в первую минуту после передачи исполнителю.

chat.available

boolean

заказ передан исполнителю; при false чат отвечает 409 chat_not_ready

chat.can_confirm / can_dispute / can_withdraw

boolean

какие из POST …/confirm, …/dispute, …/dispute/withdraw сейчас пройдут; у завершённого заказа всегда false

chat.messages_url

string

путь к переписке

chat.auto_confirm_in

string

подсказка для человека о сроке автоподтверждения; не разбирать программно

Чат с исполнителем

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

Response

{
  "order_public_id": "f80d95fb-2888-4108-8b6c-79704eb09b92",
  "status": "awaiting_confirmation",
  "manual_state": "fulfilled",
  "can_confirm": true,
  "can_dispute": true,
  "can_withdraw": false,
  "stale": false,
  "messages": [
    { "id": "m1", "sender_role": "system", "type": "system", "body": "Исполнитель принял заказ", "created_at": "2026-09-12T10:01:00Z" },
    { "id": "m2", "sender_role": "seller", "sender": "Исполнитель", "type": "text", "body": "Пришлите логин и пароль от аккаунта Microsoft", "created_at": "2026-09-12T10:02:10Z" },
    { "id": "m3", "sender_role": "client", "type": "text", "body": "login@example.com / ********", "created_at": "2026-09-12T10:05:44Z" },
    { "id": "m4", "sender_role": "seller", "sender": "Исполнитель", "type": "text", "body": "Подписка активирована, проверьте", "created_at": "2026-09-12T10:19:30Z" }
  ]
}

Переписка целиком, по времени. sender_role: seller — исполнитель, client — покупатель (ваши сообщения), system — служебные. manual_state и can_* здесь — актуальные на момент запроса. stale: true означает, что исполнитель сейчас недоступен и отдана сохранённая копия переписки. История хранится у нас и доступна после завершения заказа.

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

Request

{ "body": "login@example.com / ********" }

Текст до 4000 символов, длиннее — 400 invalid_input. Ответ — { "message": { … } } с отправленным сообщением. У завершённого заказа — 409 order_closed.

Подтверждение, спор и снятие спора

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

Response

{ "ok": true, "status": "completing" }

Подтвердить получение. Доступно в awaiting_confirmation и dispute; иначе 409 confirm_failed. completing — подтверждение принято; заказ станет completed в течение минуты (вебхук order.status). Повтор для уже завершённого заказа отвечает 200 со status: completed.

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

Request · Response

{ "reason": "Подписка не активировалась" }

{ "ok": true, "status": "dispute" }

Открыть спор. reason необязателен (до 4000 символов). Доступно только в awaiting_confirmation; иначе 409 dispute_failed. Пока спор открыт, автоподтверждение не срабатывает.

POST/api/partner/v1/orders/{public_id}/dispute/withdraw

Response

{ "ok": true, "status": "awaiting_confirmation" }

Снять свой спор. Доступно только в dispute; иначе 409 withdraw_failed.

Права: чтение переписки — любым действующим токеном; POST-действия (сообщение, подтверждение, спор) — токеном с любым правом создания заказов, иначе 403 insufficient_scope.

Ошибки чата: 404 order_not_found — заказ не ваш или не существует; 400 not_chat_order — заказ не ручной; 409 chat_not_ready — заказ ещё не оплачен; 409 order_closed — заказ завершён, чат закрыт; 409 message_rejected — исполнитель не принял сообщение; 502 provider_error — исполнитель не ответил: сообщение не отправлено, действие не выполнено — повторите через несколько секунд (при чтении в этом случае приходит сохранённая копия со stale: true); 503 chat_unavailable — у заказа нет чата на нашей стороне, обратитесь в поддержку.

POSTВозврат заказа

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

Возвращает покупателю оплату по заказу, который был оплачен платёжной ссылкой и закончился ошибкой выдачи. Возврат идёт на полную сумму платежа; комиссия эквайринга (fee.rub, fee.percent, по умолчанию 3 %) удерживается с вашего партнёрского баланса.

Условия

Токен с правом orders_refund; заказ принадлежит вам.
Заказ в статусе failed (409 invalid_state иначе).
На балансе хватает на комиссию возврата (409 insufficient_balance иначе; возврат не выполняется).
Платёж проведён эквайером с refund-API: СБП. Карта и СБП через эквайер без refund-API (409 not_refundable_acquirer_order) и криптовалюта (409 not_refundable_crypto_order) возвращаются через поддержку.

Повторный вызов для заказа в статусе refunded возвращает { "order": { … } } без fee; параллельный повтор — 409 refund_already_attempted. Отказ провайдера — 409 refund_provider_failed (можно повторить), неизвестный результат — 409 refund_status_unknown (в поддержку с public_id).

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

Возвращает текущий баланс партнёра и последние операции. Параметр limit — число операций (по умолчанию 50, максимум 200); применённое значение отдаётся в transactions_limit.

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

корректировка

Вебхуки

Если в запросе создания заказа передан webhook_url, мы отправляем на него POST-уведомления о смене статуса и о новых сообщениях в чате ручного заказа. webhook_secret необязателен: если задан, каждое уведомление подписано.

Требования к webhook_url

Только https, порт 443 или 8443, публичный хост (частные и локальные адреса отклоняются), длина до 2048 символов; иначе 400 invalid_webhook_url.

События

order.status

event

смена статуса заказа: payment_received · awaiting_confirmation · dispute · completed · failed · canceled · refunded · chargeback · creation_failed

order.message

event

новое сообщение в чате ручного заказа от исполнителя (sender_role: seller) или служебное (system); ваши сообщения (client) событием не дублируются. Тело сообщения — в объекте message, message.message_id совпадает с id в GET …/messages

Статус processing_payout отдельным событием не приходит: он наступает сразу после payment_received. По каждому статусу событие order.status отправляется один раз за жизнь заказа: если статус повторился (после снятия спора заказ снова awaiting_confirmation), второго уведомления нет — актуальное состояние берите из ответа действия или GET /orders/{public_id}.

Payload · order.status

{
  "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,
  "create_type": "api",
  "attempt": 1,
  "ts": "2026-05-21T07:09:43Z"
}

Payload · order.message

{
  "event": "order.message",
  "entity": "order",
  "public_id": "f80d95fb-2888-4108-8b6c-79704eb09b92",
  "order_public_id": "f80d95fb-2888-4108-8b6c-79704eb09b92",
  "amount_rub": 1290.00,
  "create_type": "api",
  "attempt": 1,
  "ts": "2026-09-12T10:19:31Z",
  "message": {
    "message_id": "m4",
    "sender_role": "seller",
    "sender": "Исполнитель",
    "type": "text",
    "body": "Подписка активирована, проверьте",
    "created_at": "2026-09-12T10:19:30Z"
  }
}

event

string

тип события

entity / public_id

string

что изменилось и его идентификатор (order_public_id — дубль для заказов)

status

string

новый статус; у order.message отсутствует

amount_rub

number

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

create_type

string

канал создания заказа: api · widget · bot

attempt / ts

number / string

номер попытки доставки (с 1) и время этой попытки (RFC3339 UTC); у повтора они другие, поэтому другая и подпись

message

object

только order.message: message_id, sender_role, sender, type, body, created_at

Заголовки и подпись

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

X-Payli-Signature = sha256=<hex HMAC-SHA256(тело как получено, webhook_secret)>, hex в нижнем регистре; сравнивайте за константное время и до разбора тела. Если webhook_secret не передан — заголовка нет. X-Payli-Event-Id одинаков у всех попыток одного события.

Доставка и обработка

Доставлено = любой ответ 2xx в течение 8 секунд. Обрабатывайте асинхронно и отвечайте сразу.
Иначе повтор с растущей паузой: 30 с, 1, 2, 4, 8, 16, 32 мин — всего до 8 попыток, около часа. После этого событие больше не отправляется — сверяйте состояние через GET /orders/{public_id}.
Вебхук может прийти повторно — дедуплицируйте по X-Payli-Event-Id. Порядок доставки не гарантируется: сообщения сортируйте по message.created_at, статус сверяйте по GET.
Уведомления формируются по опросу состояния раз в 30 секунд; по ручным заказам состояние исполнителя сверяется раз в минуту, так что событие может прийти с задержкой до 1–2 минут. При быстрой смене статусов промежуточное событие может не прийти — конечные статусы приходят всегда.
Возврат покупателя на redirect_url не подтверждает оплату — подтверждение приходит вебхуком.
Для криптовалютных платежей статус меняется только после подтверждения платежа провайдером и нашей сверки суммы.

Ошибки

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

HTTP	error	Когда возникает	Что делать
400	invalid_json	тело не JSON или в POST /orders передано неизвестное поле	исправить тело запроса
400	invalid_input	поля не прошли проверку: не те обязательные поля товара, тип товара не совпадает с type, пустой или длиннее 4000 символов текст сообщения; подробности в message	исправить поля по message и карточке товара
400	invalid_type	неизвестный type заказа	steam · topup · voucher · esim · manual
400	invalid_product_id	product_id не число или не передан там, где обязателен	взять id из каталога
400	invalid_category_id	category_id в пути не число	взять id из /categories
400	invalid_public_id	public_id в пути не UUID	проверить идентификатор заказа
400	invalid_payment_method	неизвестный payment_method	sbp (acquirer) · card · crypto · balance
400	invalid_partner_commission_percent	partner_commission_percent вне допустимого диапазона	проверить наценку
400	invalid_total_commission_percent	Steam: суммарная комиссия с вашей наценкой вне допустимого диапазона	уменьшить partner_commission_percent
400	amount_too_large	Steam: amount_pay_rub больше 1 000 000 ₽	уменьшить сумму
400	steam_login_invalid	Steam: логин не найден	проверить account
400	invalid_redirect_url	redirect_url не http(s)-URL или длиннее 2048 символов	проверить URL
400	invalid_webhook_url	webhook_url не https, порт не 443/8443, непубличный хост или длиннее 2048 символов	https://host[:443\|8443]/path на публичном домене
400	invalid_webhook_secret	webhook_secret длиннее 512 символов	сократить секрет
400	invalid_idempotency_key	idempotency_key длиннее 128 символов	сократить ключ
400	renew_not_available	продление eSIM запрошено, но текущий пакет ещё не закончился (трафик не израсходован и срок не истёк) либо прошло больше 30 дней после его окончания	продлевать после окончания пакета и в течение 30 дней; смотреть esim.packages / esim.renewable_now
400	renew_not_supported	eSIM не поддерживает продление	оформить новую eSIM
400	renew_not_resolvable	не удалось определить eSIM по renew_iccid / renew_order_id	проверить идентификатор
400	not_chat_order	чат запрошен у заказа не ручной выдачи	чат есть только у type: manual
401	unauthorized	токен не передан, неверен или отозван	проверить Authorization: Bearer
403	insufficient_scope	у токена нет права на действие: создание заказа (нужен scope создания для выбранного payment_method) или POST-действие в чате ручного заказа	запросить расширение прав токена
403	forbidden	у токена нет права orders_refund (возврат) или прав на инвойсы	запросить расширение прав токена
404	order_not_found	заказ не существует или принадлежит другому партнёру	проверить public_id
404	product_not_found	товар не найден или скрыт	проверить product_id по каталогу
404	category_not_found	категория не найдена	проверить category_id
405	method_not_allowed	метод не поддерживается этим путём	проверить метод (GET/POST)
409	request_in_progress	запрос с тем же idempotency_key ещё выполняется	повторить после Retry-After
409	insufficient_balance	на балансе партнёра не хватает: на оплату заказа с баланса или на комиссию возврата	пополнить баланс
409	invalid_state	возврат: заказ не в статусе failed; инвойс: статус не позволяет операцию	проверить статус
409	chat_not_ready	ручной заказ ещё не оплачен и не передан исполнителю	дождаться processing_payout
409	order_closed	ручной заказ уже завершён: чат и действия закрыты	повтор confirm у completed-заказа отвечает 200
409	confirm_failed	исполнитель ещё не отметил выдачу — подтверждать нечего	дождаться awaiting_confirmation (chat.can_confirm)
409	dispute_failed	спор нельзя открыть: выдача не отмечена или спор уже открыт	сверить chat.can_dispute
409	withdraw_failed	по заказу нет открытого спора	сверить chat.can_withdraw
409	message_rejected	исполнитель не принял сообщение: чат по заказу закрыт	смотреть статус заказа
409	refund_not_supported	платёж проведён провайдером без refund-API	возврат через поддержку
409	refund_already_attempted	возврат по заказу уже запрошен	дождаться статуса refunded или обратиться в поддержку
409	refund_provider_failed	провайдер отказал в возврате	повторить позже или обратиться в поддержку
409	refund_status_unknown	результат возврата у провайдера неизвестен	обратиться в поддержку с public_id
409	not_refundable_acquirer_order	заказ оплачен через эквайер без refund-API (СБП или карта)	возврат через поддержку
409	not_refundable_crypto_order	заказ оплачен криптовалютой	возврат через поддержку
413	payload_too_large	тело запроса больше лимита (1 МБ для заказов, 32 КБ для сообщений чата)	сократить запрос
422	invalid_amount	Steam: зачисляемая сумма вне min_rub…max_rub сервиса	изменить amount_pay_rub
429	rate_limited	превышен лимит запросов (GET 600/мин, POST 60/мин на токен)	повторить после Retry-After
429	too_many_concurrent_requests	больше 8 одновременных запросов на токен	повторить после Retry-After
500	server_error	внутренняя ошибка (также коды failed_to_*)	повторить; если повторяется — в поддержку с public_id
502	provider_error	исполнитель или поставщик не ответил: сообщение не отправлено, действие не выполнено, история не загружена	повторить через несколько секунд
502	provider_bad_response	поставщик вернул непонятный ответ при создании заказа	повторить тот же запрос с тем же idempotency_key
502	payment_url_missing	платёж создан, но провайдер не вернул pay_url	повторить тот же запрос с тем же idempotency_key
503	product_unavailable	товара нет у поставщика: закончился, снят с продажи, у ручной выдачи нет свободных исполнителей (в части сценариев приходит как 400 или 409)	повторить позже или выбрать другой товар
503	service_unavailable	сервис (Steam) временно недоступен	повторить позже
503	card_unavailable	оплата картой запрошена, но провайдер карт недоступен	использовать sbp или повторить позже
503	crypto_unavailable	оплата криптовалютой запрошена, но провайдер недоступен	использовать sbp или повторить позже
503	chat_unavailable	у заказа нет чата на нашей стороне (ошибка настройки, повторы не помогут)	обратиться в поддержку
503	fx_rate_unavailable	нет курса валюты для расчёта цены	повторить позже
503	commission_unavailable	временно недоступны правила комиссий	повторить позже
503	payment_init_recovery_pending	заказ создан, но pay_url ещё дозаписывается	повторить тот же запрос с тем же idempotency_key через пару секунд
503	idempotency_unavailable	временный сбой слоя идемпотентности	повторить позже
503	server_busy	перегрузка сервера	повторить после Retry-After