API білінгу й treasury
Сервісний баланс облікового запису та його поповнення.
Ці endpoints потребують JWT продавця й діють для облікового запису, а не для платежів покупців окремого проєкту.
| Метод | Шлях | Призначення |
|---|---|---|
| GET | /billing/me | Баланс, ставка й статус облікового запису |
| GET | /billing/ledger?page=1&limit=20 | Історія балансу з пагінацією |
| POST | /treasury/deposits | Створити намір поповнення |
| GET | /treasury/deposits | Список поповнень |
| GET | /treasury/deposits/:id | Прочитати поповнення |
| POST | /treasury/deposits/:id/cancel | Скасувати PENDING |
Гроші — десяткові рядки. Доступні способи поповнення беріть із колекції treasury відповіді GET /assets/routes. Гаманець продавця й маршрути покупецького checkout тут не використовуються.
Створення приймає { assetId, amount, idempotencyKey }. Збережіть незмінні тіло й ключ до запиту. Невідомий результат повторюйте з ними ж. Повтор може відновити старий намір навіть після вимкнення маршруту для нових поповнень. Відповідь створення може не містити пов’язаний asset: перед показом реквізитів прочитайте належне обліковому запису поповнення за ID. Кожен read потребує JWT власника; ID не є секретом доступу.
Надішліть точний expectedAmount один раз на повернену адресу, у вказаному активі/мережі й до expiresAt. Attribution-v3 зараховує номінальний requestedAmount; добавка потрібна для зіставлення. creditedAmount відображає отриманий переказ і може відрізнятися від приросту балансу. Історичні v2-поповнення зберігають розрахунок за фактично отриманим; не перераховуйте їх.
Маршрут після створення незмінний. EXPIRED приховує інструкції нового надсилання, але своєчасний переказ може підтвердитися пізніше й стати CREDITED. CANCELLED не зараховується автоматично. Помилкові й пізні перекази потребують розгляду; знайдена транзакція не означає ручне зарахування або повернення коштів.
Поля балансу й тарифу
GET /billing/me повертає десяткові рядки commissionBalance (B), commissionCreditLimit (C), remainingCommission (B+C), commissionDebt, а також creditRevision, status, tierRate, monthlyVolumeUsd, rollingVolumeUsd, billingPolicy (WEEKLY_V2 або LEGACY_V1), activationAt, period, recognitionPolicy: "FEE_POSTING_TIME". period містить startAt/endAt/windowStartAt/windowEndAt/volumeUsd; без активного тижневого періоду — null. tierRate може відображати індивідуальний тариф. Обсяг місяця не дорівнює основі періоду.
GET /billing/notifications і PUT /billing/notifications керують спільними нагадуваннями. PUT: { "enabled": true, "thresholdUsd": "5" }; поріг — додатний десятковий рядок до 18 дробових цифр і $1 000 000. Налаштування листів не змінюють допуск B+C. Реферальні винагороди мають окрему історію /referrals.