Правила сплита

Методы: /v1/split/rule · /rule/list · /rule/delete

Сплит‑платёж — правило, по которому доля каждого входящего платежа автоматически уходит партнёру. Пример: из каждых $100 — 70 % остаётся вам, 20 % уходит на адрес A, 10 % на адрес B. Типовые сценарии: партнёрские программы, реселлеры, доля площадки в маркетплейсе, разделение выручки между соучредителями.

Правила действуют на все входящие платежи мерчанта — задавать их у каждого счёта не нужно.

Базовый URL: https://api.oblodai.com · Аутентификация: обязательна.

Примеры используют хелпер call() и переменные $SECRET/$PUBLIC_ID — их определение см. в Как подписать запрос. Проще не писать подпись руками, а взять SDK.

Расчёт по сплитам не мгновенный. Он откладывается на окно удержания refund_hold_hours — см. POST /v1/split/config/get · /set. Прочитайте, почему: это не задержка ради задержки, а защита от ситуации «деньги ушли партнёру, а покупатель попросил возврат».

---

​

Два вида получателя

Это главное решение при создании правила: от него зависит, сможете ли вы вернуть деньги покупателю.

Получатель	Как задаётся	Как уходит доля	Что при возврате
Мерчант внутри Oblodai	merchant_id	Движение по внутреннему учёту (ledger).	Обратимо: доля отзывается обратно (claw‑back), пропорционально сумме возврата — даже если окно удержания уже прошло.
Внешний адрес	address + network	Реальная транзакция в блокчейне.	НЕОБРАТИМО: транзакция ушла в сеть, вернуть её нельзя. Возврат покупателю вы покрываете из своих средств.

Задавайте либо address + network, либо merchant_id — не оба сразу.

Внутренний сплит безопаснее. Если покупатель попросит возврат, платформа сама заберёт долю у партнёра. Внешний сплит уходит в блокчейн навсегда — от него вас защищает только окно удержания refund_hold_hours: пока оно не истекло, доля партнёру ещё не отправлена, и возврат покупателю возможен целиком. Полный возврат внутри окна отменяет сплит, частичный — уменьшает долю партнёра.

Не ставьте refund_hold_hours: 0 при внешних сплитах. Доли уйдут почти сразу, и вернуть их станет физически невозможно. → POST /v1/split/config/set

---

​

POST /v1/split/rule — создать правило

​

Параметры запроса

percent · float64 · обязательно

Доля от каждого платежа: 10 = 10 %, 2.5 = 2.5 %. Больше 0 и не больше 100. Точность — до 0.01 %.

address · string

Внешний криптоадрес партнёра.

network · string

Сеть адреса. Обязательна вместе с address.

merchant_id · string

Идентификатор мерчанта‑партнёра внутри Oblodai.

note · string

Комментарий для себя (в списке правил).

Ровно один вариант получателя: либо address + network, либо merchant_id.

Сумма всех правил не может превышать 100 % — иначе split.exceeds_100. Себе сплит назначить нельзя (split.self_destination).

​

Пример запроса

cURL

BODY='{"address":"TXY...","network":"tron","percent":10,"note":"партнёр Алиса"}'
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" 'POST' '/v1/split/rule' "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -s https://api.oblodai.com/v1/split/rule \
  -X POST -H 'Content-Type: application/json' \
  -H "X-Public-Id: $PUBLIC_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d "$BODY"

# 10 % на внешний адрес — необратимо.
call("/v1/split/rule", {
    "address": "TXY...",
    "network": "tron",
    "percent": 10,
    "note": "партнёр Алиса",
})

# 20 % мерчанту внутри платформы — при возврате доля отзовётся обратно.
call("/v1/split/rule", {
    "merchant_id": "b4c1f0e2-5a77-4d31-9f08-2c6e7a1b3d94",
    "percent": 20,
    "note": "площадка",
})

// 10 % на внешний адрес — необратимо.
await call("/v1/split/rule", {
  address: "TXY...",
  network: "tron",
  percent: 10,
  note: "партнёр Алиса",
});

// 20 % мерчанту внутри платформы — при возврате доля отзовётся обратно.
await call("/v1/split/rule", {
  merchant_id: "b4c1f0e2-5a77-4d31-9f08-2c6e7a1b3d94",
  percent: 20,
  note: "площадка",
});

​

Пример ответа

{
  "state": 0,
  "result": {
    "rule_id": "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23",
    "percent": 10
  }
}

---

​

POST /v1/split/rule/list — список правил

Параметров нет — пошлите {}.

Python

call("/v1/split/rule/list", {})

await call("/v1/split/rule/list", {});

​

Пример ответа

{
  "state": 0,
  "result": {
    "items": [
      {
        "rule_id": "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23",
        "percent": 10,
        "active": true,
        "note": "партнёр Алиса",
        "address": "TXY...",
        "network": "tron",
        "reversible": false
      },
      {
        "rule_id": "7b3d0f19-6c25-4e88-b0a4-1f9e2d5c8a07",
        "percent": 20,
        "active": true,
        "note": "площадка",
        "merchant_id": "b4c1f0e2-5a77-4d31-9f08-2c6e7a1b3d94",
        "reversible": true
      }
    ]
  }
}

rule_id · string

Идентификатор правила.

percent · float

Доля от каждого платежа, %.

active · bool

Действует ли правило.

note · string

Ваш комментарий.

address · string

Получатель — внешний адрес (только у внешних правил).

network · string

Сеть внешнего адреса (только у внешних правил).

merchant_id · string

Получатель — мерчант платформы (только у внутренних правил).

reversible · bool

true — доля отзывается при возврате платежа (внутренний сплит); false — уходит в блокчейн навсегда (внешний).

---

​

POST /v1/split/rule/delete — удалить правило

​

Параметры запроса

rule_id · string · обязательно

Идентификатор правила.

Python

call("/v1/split/rule/delete", {"rule_id": "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23"})

await call("/v1/split/rule/delete", { rule_id: "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23" });

​

Пример ответа

{ "state": 0, "result": { "deleted": true } }

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

---

​

Коды ошибок

Код	Значение
400 request.bad_json	Тело не парсится.
400 split.bad_destination	Не задан получатель, либо заданы оба (address и merchant_id).
400 split.network_required	Задан address, но не задана network.
400 split.bad_percent	percent вне диапазона 0–100.
400 split.exceeds_100	Сумма долей всех правил превысила 100 %.
400 split.bad_merchant	merchant_id не является корректным UUID.
400 split.self_destination	Получатель — вы сами.
400 split.bad_id	rule_id не является корректным UUID.
404 split.not_found	Правило не найдено.
503 split.disabled	Сплит‑платежи недоступны на этом шлюзе.
401 auth.*	Ошибки аутентификации.

---

​

Нюансы

• Сплит — пятый путь ухода средств с вашего баланса (наряду с выплатой, возвратом, автовыводом и переводом на личный кошелёк). Учитывайте его, когда сводите баланс.
• База расчёта — то, что реально пришло, за вычетом возвратов. Доля считается от суммы платежа на момент исполнения, а не от суммы счёта: возврат внутри окна удержания уменьшает или обнуляет долю.
• Доля уходит в монете платежа. Отдельной конвертации сплит не делает.
• Внешние сплиты необратимы. Если вам нужна возможность отката, используйте merchant_id (внутренний сплит) — либо держите достаточное окно refund_hold_hours.

---

​

Связанные страницы

POST /v1/split/config/get · /set

окно удержания refund_hold_hours и почему оно нужно.

POST /v1/payment/refund

как возврат взаимодействует со сплитами.

POST /v1/balance

POST /v1/auto-withdraw/*