> ## Documentation Index > Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Сплит‑платежи: автоматическое разделение выручки Сплит — это правило «с каждого входящего платежа отдавай N % туда‑то». Настроили один раз — дальше доли уходят партнёрам автоматически, без единого вызова API на каждый платёж. Пример: покупатель заплатил **\$100**. У вас настроены два правила — 20 % на адрес партнёра A и 10 % на адрес партнёра B. Итог: **\$70 остаётся вам**, **\$20 уходит A**, **\$10 уходит B**. Вам не нужно ловить вебхук, считать доли и вызывать выплаты — шлюз делает это сам. Справочник методов — [`POST /v1/split/rule`](/reference/split-rule) и [`POST /v1/split/config/get · /set`](/reference/split-config). *** ## Зачем это нужно * **Партнёрские программы** — реферал приводит клиента и получает свой процент с каждой его оплаты. * **Маркетплейс / площадка** — комиссия площадки остаётся вам, остальное уходит продавцу. * **Совместные проекты** — двое соавторов делят выручку 50/50, не сводя счёты вручную. * **Агентские выплаты** — менеджер получает процент со сделок, которые он закрыл. *** ## Шаг 1. Создать правило Правило описывает **одного получателя** и **его долю**. Получателей может быть несколько — создайте несколько правил. Есть два вида назначения, и разница между ними существеннее, чем кажется. ### Вариант А. На внешний адрес ```python Python theme={null} call("/v1/split/rule", { "address": "TXY…", # внешний блокчейн-адрес партнёра "network": "tron", # обязательна вместе с address "percent": 20.0, # 20 % с каждого входящего платежа "note": "Партнёр A", # ваша пометка, чтобы не запутаться }) ``` ```js Node.js theme={null} await call("/v1/split/rule", { address: "TXY…", // внешний блокчейн-адрес партнёра network: "tron", // обязательна вместе с address percent: 20.0, // 20 % с каждого входящего платежа note: "Партнёр A", // ваша пометка, чтобы не запутаться }); ``` Деньги уходят из шлюза наружу, в блокчейн. Обратно их не вернуть. ### Вариант Б. На мерчанта внутри платформы ```python Python theme={null} call("/v1/split/rule", { "merchant_id": "…", # мерчант Oblodai "percent": 10.0, "note": "Партнёр B", }) ``` ```js Node.js theme={null} 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 Python theme={null} call("/v1/split/config/set", {"refund_hold_hours": 72}) # держим 72 часа call("/v1/split/config/get", {}) # посмотреть текущее ``` ```js Node.js theme={null} 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 Python theme={null} rules = call("/v1/split/rule/list", {})["result"] # по каждому правилу видно: назначение, percent, note, rule_id # удалить правило (новые платежи по нему делиться не будут) call("/v1/split/rule/delete", {"rule_id": "…"}) ``` ```js Node.js theme={null} 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 %) = ваша чистая часть ``` Не забывайте про это, планируя экономику: партнёру уходит доля с суммы, а не «сверх» неё — итоговая маржа считается после **обеих** комиссий. → [Модель баланса и движение средств](/guides/balance-and-funds) *** ## Ошибки | Код | Значение | Что делать | | ---------------------------------- | ---------------------------------------------------- | ---------------------------------------------- | | `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. | *** ## Связанные страницы окно удержания. сплит как путь ухода средств. почему возврат списывает всю сумму. ручной вывод, если сплит не подходит.