Сплит‑платежи: автоматическое разделение выручки

Сплит — это правило «с каждого входящего платежа отдавай N % туда‑то». Настроили один раз — дальше доли уходят партнёрам автоматически, без единого вызова API на каждый платёж.

Пример: покупатель заплатил $100. У вас настроены два правила — 20 % на адрес партнёра A и 10 % на адрес партнёра B. Итог: $70 остаётся вам, $20 уходит A, $10 уходит B. Вам не нужно ловить вебхук, считать доли и вызывать выплаты — шлюз делает это сам.

Справочник методов — POST /v1/split/rule и POST /v1/split/config/get · /set.

---

​

Зачем это нужно

• Партнёрские программы — реферал приводит клиента и получает свой процент с каждой его оплаты.
• Маркетплейс / площадка — комиссия площадки остаётся вам, остальное уходит продавцу.
• Совместные проекты — двое соавторов делят выручку 50/50, не сводя счёты вручную.
• Агентские выплаты — менеджер получает процент со сделок, которые он закрыл.

---

​

Шаг 1. Создать правило

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

Есть два вида назначения, и разница между ними существеннее, чем кажется.

​

Вариант А. На внешний адрес

Python

call("/v1/split/rule", {
    "address": "TXY…",          # внешний блокчейн-адрес партнёра
    "network": "tron",          # обязательна вместе с address
    "percent": 20.0,            # 20 % с каждого входящего платежа
    "note": "Партнёр A",        # ваша пометка, чтобы не запутаться
})

await call("/v1/split/rule", {
  address: "TXY…",          // внешний блокчейн-адрес партнёра
  network: "tron",          // обязательна вместе с address
  percent: 20.0,            // 20 % с каждого входящего платежа
  note: "Партнёр A",        // ваша пометка, чтобы не запутаться
});

Деньги уходят из шлюза наружу, в блокчейн. Обратно их не вернуть.

​

Вариант Б. На мерчанта внутри платформы

Python

call("/v1/split/rule", {
    "merchant_id": "…",         # мерчант Oblodai
    "percent": 10.0,
    "note": "Партнёр B",
})

await call("/v1/split/rule", {
  merchant_id: "…",         // мерчант Oblodai
  percent: 10.0,
  note: "Партнёр B",
});

Деньги перекладываются внутри платформы, с баланса на баланс — движением по внутреннему учёту, без блокчейна. Главное преимущество: такой сплит обратим. Если платёж вернут покупателю, доля партнёра будет отозвана с его баланса обратно — автоматически и пропорционально сумме возврата (вернули половину платежа → с партнёра снимут половину его доли).

Задавайте либо address + network, либо merchant_id — не оба сразу (иначе split.bad_destination). И то и другое одновременно шлюз не примет.

	Внешний адрес	Мерчант внутри платформы
Куда уходит	В блокчейн, наружу	На баланс другого мерчанта
Комиссия сети	Платится (это реальная транзакция)	Нет
Возврат покупателю после раздачи	НЕОБРАТИМО. Долю не отозвать — транзакция в блокчейне окончательна. Возврат вы платите из своего кармана.	Доля отзывается обратно, пропорционально возврату.
Когда выбрать	Партнёр вне платформы	Партнёр тоже работает с Oblodai

Если партнёр есть в платформе — выбирайте merchant_id. Это и дешевле (нет комиссии сети), и принципиально безопаснее при возвратах. Внешний адрес — это дверь в одну сторону.

---

​

Шаг 2. Настроить окно удержания (refund_hold_hours)

Это самая важная настройка сплитов. Её нужно понять, а не просто выставить: цена ошибки здесь — ваши собственные деньги.

Python

call("/v1/split/config/set", {"refund_hold_hours": 72})   # держим 72 часа
call("/v1/split/config/get", {})                          # посмотреть текущее

await call("/v1/split/config/set", { refund_hold_hours: 72 });   // держим 72 часа
await call("/v1/split/config/get", {});                          // посмотреть текущее

Доли уходят партнёрам не сразу. Сначала платёж «отлёживается» refund_hold_hours часов, и только потом происходит расчёт по сплитам.

​

Это не бюрократическая задержка, а окно возвратности

Вот суть, из которой следует всё остальное:

Возврат покупателю списывает с ВАШЕГО баланса ВСЮ сумму, которую он заплатил. Не вашу долю после раздачи партнёрам — все 100 %. Шлюз не ходит к внешним партнёрам собирать деньги обратно: перевод на внешний адрес — это транзакция в блокчейне, она необратима.

Значит, пока доли не розданы, возврат безболезнен, а как только розданы — вы платите за него сами. Окно удержания — это ровно тот промежуток, внутри которого возврат ещё можно провести целиком.

Что происходит внутри окна:

Событие внутри окна	Что делает шлюз
Полный возврат	Сплит отменяется целиком. Партнёрам не уходит ничего. Ваш убыток — ноль.
Частичный возврат	Доля партнёра пересчитывается вниз пропорционально: вернули половину платежа → партнёр получит половину доли.
Возврата не было, окно истекло	Доли уходят партнёрам. С этого момента платёж «раздан».

Что происходит после окна — зависит от вида партнёра:

Возврат после раздачи	Внутренний партнёр (merchant_id)	Внешний адрес (address)
Что с долей	Отзывается с баланса партнёра, пропорционально возврату	Не отзывается. Никак.
Кто платит возврат	Платформа разруливает по ledger	Вы, из своего кармана

​

На цифрах: почему без окна вы уходите в минус

Сценарий без окна удержания (refund_hold_hours: 0), партнёр — на внешнем адресе:

Покупатель заплатил              $100
Сразу разошлось партнёрам        -$30   (20 % + 10 %) → УШЛО В БЛОКЧЕЙН, необратимо
У вас на балансе                  $70

Покупатель просит возврат        -$100  ← списывается с ВАС, целиком
Итог                              -$30  ← чистый убыток: вы вернули чужие доли своими деньгами

Тот же сценарий с окном удержания:

Покупатель заплатил              $100   → лежит у вас целиком
[окно удержания, напр. 72 часа]
  ├─ Полный возврат?     → вернули $100, партнёрам не ушло НИЧЕГО. Убыток $0.
  ├─ Частичный ($50)?    → доля партнёров пересчиталась: вместо $30 уйдёт $15.
  └─ Возврата не было?   → окно закрылось, партнёрам ушло $30, у вас осталось $70.

​

refund_hold_hours: 0 — опасное значение

Ноль означает «раздавать доли немедленно». Это снимает единственную защиту от описанного выше убытка: возврат по внешнему сплиту становится невозможно покрыть из денег партнёра — покрывать будете вы, из своего кармана, на каждом возврате.

Ставьте 0 только если вы твёрдо уверены, что возвратов по этим платежам не бывает в принципе.

​

Как выбрать значение

Ориентируйтесь на свой реальный срок возвратов: сколько времени проходит между оплатой и типичной жалобой клиента. Окно должно перекрывать его с запасом.

• Слишком маленькое окно → партнёры получают деньги раньше, чем вы узнаёте о проблеме. Риск оплатить возврат из своего кармана.
• Слишком большое окно → партнёры дольше ждут свои деньги и жалуются.

Компромисс ищется между этими двумя, но ошибаться безопаснее в сторону большего окна: недовольный задержкой партнёр — это разговор, а невозвратный убыток — это деньги.

Сплиты на merchant_id мягче к возвратам: доля отзывается с баланса партнёра даже после закрытия окна. Но и там окно полезно — оно избавляет партнёра от «качелей» на балансе (получил → отобрали).

---

​

Шаг 3. Проверить, что получилось

Python

rules = call("/v1/split/rule/list", {})["result"]
# по каждому правилу видно: назначение, percent, note, rule_id

# удалить правило (новые платежи по нему делиться не будут)
call("/v1/split/rule/delete", {"rule_id": "…"})

const rules = (await call("/v1/split/rule/list", {})).result;
// по каждому правилу видно: назначение, percent, note, rule_id

// удалить правило (новые платежи по нему делиться не будут)
await call("/v1/split/rule/delete", { rule_id: "…" });

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

---

​

Как сплиты влияют на баланс

Сплит — это пятый путь ухода средств с вашего баланса, наравне с выплатой, автовыводом, возвратом и переводом на личный кошелёк. Отличие в том, что вы его не инициируете: он срабатывает сам, по правилу.

Сумма, из которой считается доля, — та, что реально зачислилась. Порядок такой:

Покупатель заплатил                     100 USDT
− комиссия платформы (1.5 % + $0.30)   ≈  −1.80
= зачислено на баланс                  ≈  98.20 USDT
    ↓ [окно удержания]
− доли партнёров (30 %)
= ваша чистая часть

Не забывайте про это, планируя экономику: партнёру уходит доля с суммы, а не «сверх» неё — итоговая маржа считается после обеих комиссий.

→ Модель баланса и движение средств

---

​

Ошибки

Код	Значение	Что делать
split.bad_destination	Заданы и address, и merchant_id — или ни одного.	Выберите ровно одно назначение.
split.network_required	Задан address без network.	Укажите сеть адреса.
split.bad_percent	Некорректная доля.	Проверьте percent.
split.bad_merchant	Мерчант‑получатель не найден.	Сверьте merchant_id.
split.self_destination	Правило указывает на вас самих.	Себе платить не нужно — остаток и так ваш.
split.bad_hold	Некорректное refund_hold_hours.	Проверьте значение.
split.bad_id / split.not_found	Правило не найдено.	Сверьте rule_id через /v1/split/rule/list.
split.disabled (503)	Сплиты временно выключены.	Временная ошибка — повторите с backoff.

---

​

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

POST /v1/split/rule · /list · /delete

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

окно удержания.

Модель баланса и движение средств

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

Возвраты платежей

почему возврат списывает всю сумму.

Первая выплата

ручной вывод, если сплит не подходит.