Loading documentation...
Preparing Ring content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring content
Preparing Ring content
Preparing Ring content
Фільтруйте цю сторінку як Founder / Developer у бічній панелі. Засновники дізнаються що коштує кожен провайдер і як налаштувати комісії; розробники — архітектуру, контракти модулів провайдерів і деталі cron-пайплайнів.
SubscriptionConductor (v1, Фаза S4) — мульти-провайдерна система білінгу членських підписок Ring Platform. Один SSOT-реєстр (subscription_ledger) відстежує всі стани підписників незалежно від способу оплати. Шість модулів провайдерів реалізують спільний контракт SubscriptionProviderModule, а п'ять cron-пайплайнів підтримують підписки актуальними.
Реалізація: lib/payments/subscription/.
Ваша платформа заробляє регулярний дохід через членські підписки — з нульовою комісією платформи на внутрішні методи (кредитний баланс, RING-токен, NFT-гейт). Оберіть, які шлюзи увімкнути, налаштуйте перекладення комісій і відстежуйте чистий дохід в адмін-панелі.
| Провайдер | Деталі | Шлюз | Статус |
|---|---|---|---|
| WayForPay | рекурентний білінг через recToken | WayForPay (UAH) | ✅ Доступно |
| Кредитний баланс | автосписання з внутрішніх RING-кредитів | Кредитні бали | ✅ Доступно |
| RING-токен | ончейн-платіж у Solana | RING (Токени) | ✅ Доступно |
| Stripe | Stripe Subscriptions API | Stripe (USD) | 🔮 TBD |
| NFT-гейт | 12-місячний доступ через soulbound NFT | NFT Сертифікат | 🔮 TBD |
| PayPal | PayPal рекурентний білінг | PayPal (USD) | 🔮 TBD |
Кожен шлюз утримує власну комісію. Внутрішні методи (кредитний баланс, RING-токен, NFT-гейт) стягують 0% — кожен долар іде вашій платформі.
| Провайдер | Комісія % | Фіксована комісія | Валюта |
|---|---|---|---|
| WayForPay | 2.5% | — | UAH |
| Stripe | 2.9% | $0.30 | USD |
| Кредитний баланс | 0% | — | USD |
| RING-токен | 0% | — | RING (Токени) |
| NFT-гейт | 0% | — | RING |
| PayPal |
Формула чистого доходу: net = gross - (gross × feePercent / 100) - feeFixed. Функція calculateNetRevenue() у subscription-config.ts обчислює це на сервері; адмін-панель показує gross, fee та net для кожної підписки.
Усі налаштування провайдерів зберігаються в ring-config.json у секції payment.gateways:
cardPaymentProcessor — картковий шлюз за замовчуванням (wayforpay або stripe). Перевизначення через PAYMENT_MEMBERSHIP_PROCESSOR=stripe.supportedMethods — провайдери, доступні користувачам при оформленні.futureMethods — провайдери з позначкою "Незабаром" в UI.gateways.<provider>.feePercent — відсоткова комісія, що утримується перед вашим чистим доходом.Супер-адміни мають доступ до /admin/subscriptions:
/api/admin/subscriptions/stats повертає total_active, due_for_payment, розбивки by_provider та by_method.calculateNetRevenue() викликається для кожного рядка, щоб засновники бачили реальний дохід після комісій шлюзів.Фільтруйте цю сторінку як Founder / Developer у бічній панелі. Засновники дізнаються що коштує кожен провайдер і як налаштувати комісії; розробники — архітектуру, контракти модулів провайдерів і деталі cron-пайплайнів.
SubscriptionConductor (v1, Фаза S4) — мульти-провайдерна система білінгу членських підписок Ring Platform. Один SSOT-реєстр (subscription_ledger) відстежує всі стани підписників незалежно від способу оплати. Шість модулів провайдерів реалізують спільний контракт SubscriptionProviderModule, а п'ять cron-пайплайнів підтримують підписки актуальними.
Реалізація: lib/payments/subscription/.
Ваша платформа заробляє регулярний дохід через членські підписки — з нульовою комісією платформи на внутрішні методи (кредитний баланс, RING-токен, NFT-гейт). Оберіть, які шлюзи увімкнути, налаштуйте перекладення комісій і відстежуйте чистий дохід в адмін-панелі.
| Провайдер | Деталі | Шлюз | Статус |
|---|---|---|---|
| WayForPay | рекурентний білінг через recToken | WayForPay (UAH) | ✅ Доступно |
| Кредитний баланс | автосписання з внутрішніх RING-кредитів | Кредитні бали | ✅ Доступно |
| RING-токен | ончейн-платіж у Solana | RING (Токени) | ✅ Доступно |
| Stripe | Stripe Subscriptions API | Stripe (USD) | 🔮 TBD |
| NFT-гейт | 12-місячний доступ через soulbound NFT | NFT Сертифікат | 🔮 TBD |
| PayPal | PayPal рекурентний білінг | PayPal (USD) | 🔮 TBD |
Кожен шлюз утримує власну комісію. Внутрішні методи (кредитний баланс, RING-токен, NFT-гейт) стягують 0% — кожен долар іде вашій платформі.
| Провайдер | Комісія % | Фіксована комісія | Валюта |
|---|---|---|---|
| WayForPay | 2.5% | — | UAH |
| Stripe | 2.9% | $0.30 | USD |
| Кредитний баланс | 0% | — | USD |
| RING-токен | 0% | — | RING (Токени) |
| NFT-гейт | 0% | — | RING |
| PayPal |
Формула чистого доходу: net = gross - (gross × feePercent / 100) - feeFixed. Функція calculateNetRevenue() у subscription-config.ts обчислює це на сервері; адмін-панель показує gross, fee та net для кожної підписки.
Усі налаштування провайдерів зберігаються в ring-config.json у секції payment.gateways:
cardPaymentProcessor — картковий шлюз за замовчуванням (wayforpay або stripe). Перевизначення через PAYMENT_MEMBERSHIP_PROCESSOR=stripe.supportedMethods — провайдери, доступні користувачам при оформленні.futureMethods — провайдери з позначкою "Незабаром" в UI.gateways.<provider>.feePercent — відсоткова комісія, що утримується перед вашим чистим доходом.Супер-адміни мають доступ до /admin/subscriptions:
/api/admin/subscriptions/stats повертає total_active, due_for_payment, розбивки by_provider та by_method.calculateNetRevenue() викликається для кожного рядка, щоб засновники бачили реальний дохід після комісій шлюзів.Фільтруйте цю сторінку як Founder / Developer у бічній панелі. Засновники дізнаються що коштує кожен провайдер і як налаштувати комісії; розробники — архітектуру, контракти модулів провайдерів і деталі cron-пайплайнів.
SubscriptionConductor (v1, Фаза S4) — мульти-провайдерна система білінгу членських підписок Ring Platform. Один SSOT-реєстр (subscription_ledger) відстежує всі стани підписників незалежно від способу оплати. Шість модулів провайдерів реалізують спільний контракт SubscriptionProviderModule, а п'ять cron-пайплайнів підтримують підписки актуальними.
Реалізація: lib/payments/subscription/.
Ваша платформа заробляє регулярний дохід через членські підписки — з нульовою комісією платформи на внутрішні методи (кредитний баланс, RING-токен, NFT-гейт). Оберіть, які шлюзи увімкнути, налаштуйте перекладення комісій і відстежуйте чистий дохід в адмін-панелі.
| Провайдер | Деталі | Шлюз | Статус |
|---|---|---|---|
| WayForPay | рекурентний білінг через recToken | WayForPay (UAH) | ✅ Доступно |
| Кредитний баланс | автосписання з внутрішніх RING-кредитів | Кредитні бали | ✅ Доступно |
| RING-токен | ончейн-платіж у Solana | RING (Токени) | ✅ Доступно |
| Stripe | Stripe Subscriptions API | Stripe (USD) | 🔮 TBD |
| NFT-гейт | 12-місячний доступ через soulbound NFT | NFT Сертифікат | 🔮 TBD |
| PayPal | PayPal рекурентний білінг | PayPal (USD) | 🔮 TBD |
Кожен шлюз утримує власну комісію. Внутрішні методи (кредитний баланс, RING-токен, NFT-гейт) стягують 0% — кожен долар іде вашій платформі.
| Провайдер | Комісія % | Фіксована комісія | Валюта |
|---|---|---|---|
| WayForPay | 2.5% | — | UAH |
| Stripe | 2.9% | $0.30 | USD |
| Кредитний баланс | 0% | — | USD |
| RING-токен | 0% | — | RING (Токени) |
| NFT-гейт | 0% | — | RING |
| PayPal |
Формула чистого доходу: net = gross - (gross × feePercent / 100) - feeFixed. Функція calculateNetRevenue() у subscription-config.ts обчислює це на сервері; адмін-панель показує gross, fee та net для кожної підписки.
Усі налаштування провайдерів зберігаються в ring-config.json у секції payment.gateways:
cardPaymentProcessor — картковий шлюз за замовчуванням (wayforpay або stripe). Перевизначення через PAYMENT_MEMBERSHIP_PROCESSOR=stripe.supportedMethods — провайдери, доступні користувачам при оформленні.futureMethods — провайдери з позначкою "Незабаром" в UI.gateways.<provider>.feePercent — відсоткова комісія, що утримується перед вашим чистим доходом.Супер-адміни мають доступ до /admin/subscriptions:
/api/admin/subscriptions/stats повертає total_active, due_for_payment, розбивки by_provider та by_method.calculateNetRevenue() викликається для кожного рядка, щоб засновники бачили реальний дохід після комісій шлюзів.| 2.9% |
| $0.30 |
| USD |
nft_gatenftGateSubscriptionProvider |
providers/subscription-provider-stubs.ts |
paypal | paypalSubscriptionProvider | providers/subscription-provider-stubs.ts |
Заглушки для WayForPay, NFT Gate та PayPal є заповнювачами; Stripe, Credit Balance та RING Token мають повні реалізації.
SSOT-колекція: subscription_ledger. Схема визначена в lib/payments/subscription/subscription-ledger-schema.ts (Zod).
Ключові поля:
| Поле | Тип | Опис |
|---|---|---|
id | string | ID рядка реєстру (sub_<ts>_<userIdSuffix>) |
user_id | string | ID користувача-власника |
provider | enum | stripe, wayforpay, credit_balance, ring_token, nft_gate, paypal |
gateway | string | Людино-читана мітка (напр. "Stripe", "WayForPay") |
method | enum | card, credit_balance, crypto, nft |
status | enum | active, expired, cancelled, suspended, grace_period |
amount | number | Ціна підписки (у мінорних одиницях) |
currency | string | Валюта білінгу |
gateway_fee_percent | number | Відсоткова комісія (напр. 2.9) |
gateway_fee_fixed | number | Фіксована комісія в мінорних одиницях (напр. 30 для Stripe) |
stripe_subscription_id | string? | Stripe-посилання (якщо провайдер Stripe) |
wayforpay_rec_token | string? | Рекурентний токен WayForPay |
solana_tx_signature | string? | Ончейн-підпис транзакції |
nft_mint_address | string? | Адреса мінту NFT-сертифіката |
start_time | number | Початок підписки (мс епохи) |
next_payment_due | number | Час наступного платежу |
failed_attempts | number | Послідовні невдачі платежу (макс 3 → авто expiring) |
auto_renew | boolean | Прапор автоподовження |
total_paid | string | Загалом сплачено за весь час |
payments_count | number | Кількість успішних платежів |
SubscriptionConductor (lib/payments/subscription/subscription-conductor.ts) надає:
| Операція | Сигнатура | Опис |
|---|---|---|
createSubscription | (input: CreateSubscriptionInput) → CreateSubscriptionResult | Маршрутизація до модуля провайдера, вставка рядка реєстру |
cancelSubscription | (userId, provider, gatewayRef?) → CancelSubscriptionResult | Скасування у провайдера + позначка рядків реєстру |
renewSubscription | (userId, provider, gatewayRef?) → RenewSubscriptionResult | Поновлення у провайдера + оновлення реєстру |
getSubscription | (userId) → SubscriptionLedgerRow | null | Остання активна підписка користувача |
getSubscriptions | (filter) → SubscriptionLedgerRow[] | Запит за користувачем, провайдером, статусом, методом, вікном оплати |
getStats | () → SubscriptionStats | Агреговані підрахунки за статусом, провайдером, методом |
calculateNetRevenue | (row) → { gross, fee, net, currency } | Чистий дохід на рядок |
| Метод | Шлях | Призначення | Авторизація |
|---|---|---|---|
POST | /api/membership/subscription/create | Створення підписки через conductor | Сесія |
GET | /api/membership/subscription/status | Статус підписки + баланс | Сесія |
POST | /api/membership/subscription/cancel | Скасування підписки | Сесія |
POST | /api/membership/payment/token | Обробка токен-платежу | Сесія |
GET | /api/admin/subscriptions | Список усіх підписок | Суперадмін |
GET | /api/admin/subscriptions/stats | Агрегована статистика | Суперадмін |
П'ять cron-пайплайнів зареєстровані в lib/processes/registry.ts у категорії membership:
| ID пайплайну | Cron-шлях | Обробник | Розклад |
|---|---|---|---|
subscription-expiry-check | /api/cron/subscription-expiry | runSubscriptionExpiryCheck | Щодня опівночі |
credit-balance-monthly | /api/cron/credit-balance-monthly | runCreditBalanceMonthly | Щогодини |
subscription-payment | /api/cron/subscription-payment | runSubscriptionPaymentCheck | Щодня о 2:00 |
solana-batch-payment | /api/cron/solana-batch-payment | runSolanaBatchPayment | Щодня о 3:00 |
nft-gate-expiry | /api/cron/nft-gate-expiry | runNftGateExpiry | Щодня о 4:00 |
Пайплайни запускаються через HTTP cron-завдання за cronPath. Обробники імпортуються з lib/processes/subscription/:
expiry-check.ts — позначає прострочені підписки як expired і знижує ролі користувачівcredit-balance-monthly.ts — списує щомісячну плату з кредитного балансуsubscription-payment.ts — обробляє рекурентні платежі Stripe/WayForPaysolana-nft-stubs.ts — пакетні перекази RING-токенів і закінчення терміну NFT-гейтуSubscriptionProviderModule у providers/<name>-subscription.tssubscription-conductor.ts у providerRegistry Mapring-config.json payment.gateways.<provider>SUBSCRIPTION_PROVIDERS у subscription-ledger-schema.tsgetMembershipPaymentOptions() у subscription-config.tslib/processes/subscription/
{
"payment": {
"cardPaymentProcessor": "wayforpay",
"supportedMethods": ["wayforpay", "credit_balance", "ring_token"],
"futureMethods": ["stripe", "paypal", "nft_gate"],
"gateways": {
"wayforpay": { "enabled": true, "feePercent": 2.5, "currency": "UAH" },
"stripe": { "enabled": false, "feePercent": 2.9, "feeFixedCents": 30, "currency": "USD" },
"credit_balance": { "enabled": true, "feePercent": 0, "currency": "USD" },
"ring_token": { "enabled": true, "feePercent": 0, "currency": "RING", "label": "Tokens" },
"paypal": { "enabled": false, "feePercent": 2.9, "feeFixedCents": 30, "currency": "USD" },
"nft_gate": { "enabled": false, "feePercent": 0, "currency": "RING", "label": "NFT Certificate" }
}
}
}
Membership upgrade / checkout
↓
lib/payments/subscription/subscription-conductor.ts
↓
Модулі провайдерів: stripe | wayforpay | credit_balance | ring_token | nft_gate | paypal
↓
subscription_ledger (PostgreSQL — провайдер-агностичний SSOT)
↓
Cron-пайплайни: expiry + payment + credit-balance + solana-batch + nft-gate
PAYMENT_MEMBERSHIP_PROCESSOR=wayforpay # Перевизначення карткового шлюзу для членства
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...| 2.9% |
| $0.30 |
| USD |
nft_gatenftGateSubscriptionProvider |
providers/subscription-provider-stubs.ts |
paypal | paypalSubscriptionProvider | providers/subscription-provider-stubs.ts |
Заглушки для WayForPay, NFT Gate та PayPal є заповнювачами; Stripe, Credit Balance та RING Token мають повні реалізації.
SSOT-колекція: subscription_ledger. Схема визначена в lib/payments/subscription/subscription-ledger-schema.ts (Zod).
Ключові поля:
| Поле | Тип | Опис |
|---|---|---|
id | string | ID рядка реєстру (sub_<ts>_<userIdSuffix>) |
user_id | string | ID користувача-власника |
provider | enum | stripe, wayforpay, credit_balance, ring_token, nft_gate, paypal |
gateway | string | Людино-читана мітка (напр. "Stripe", "WayForPay") |
method | enum | card, credit_balance, crypto, nft |
status | enum | active, expired, cancelled, suspended, grace_period |
amount | number | Ціна підписки (у мінорних одиницях) |
currency | string | Валюта білінгу |
gateway_fee_percent | number | Відсоткова комісія (напр. 2.9) |
gateway_fee_fixed | number | Фіксована комісія в мінорних одиницях (напр. 30 для Stripe) |
stripe_subscription_id | string? | Stripe-посилання (якщо провайдер Stripe) |
wayforpay_rec_token | string? | Рекурентний токен WayForPay |
solana_tx_signature | string? | Ончейн-підпис транзакції |
nft_mint_address | string? | Адреса мінту NFT-сертифіката |
start_time | number | Початок підписки (мс епохи) |
next_payment_due | number | Час наступного платежу |
failed_attempts | number | Послідовні невдачі платежу (макс 3 → авто expiring) |
auto_renew | boolean | Прапор автоподовження |
total_paid | string | Загалом сплачено за весь час |
payments_count | number | Кількість успішних платежів |
SubscriptionConductor (lib/payments/subscription/subscription-conductor.ts) надає:
| Операція | Сигнатура | Опис |
|---|---|---|
createSubscription | (input: CreateSubscriptionInput) → CreateSubscriptionResult | Маршрутизація до модуля провайдера, вставка рядка реєстру |
cancelSubscription | (userId, provider, gatewayRef?) → CancelSubscriptionResult | Скасування у провайдера + позначка рядків реєстру |
renewSubscription | (userId, provider, gatewayRef?) → RenewSubscriptionResult | Поновлення у провайдера + оновлення реєстру |
getSubscription | (userId) → SubscriptionLedgerRow | null | Остання активна підписка користувача |
getSubscriptions | (filter) → SubscriptionLedgerRow[] | Запит за користувачем, провайдером, статусом, методом, вікном оплати |
getStats | () → SubscriptionStats | Агреговані підрахунки за статусом, провайдером, методом |
calculateNetRevenue | (row) → { gross, fee, net, currency } | Чистий дохід на рядок |
| Метод | Шлях | Призначення | Авторизація |
|---|---|---|---|
POST | /api/membership/subscription/create | Створення підписки через conductor | Сесія |
GET | /api/membership/subscription/status | Статус підписки + баланс | Сесія |
POST | /api/membership/subscription/cancel | Скасування підписки | Сесія |
POST | /api/membership/payment/token | Обробка токен-платежу | Сесія |
GET | /api/admin/subscriptions | Список усіх підписок | Суперадмін |
GET | /api/admin/subscriptions/stats | Агрегована статистика | Суперадмін |
П'ять cron-пайплайнів зареєстровані в lib/processes/registry.ts у категорії membership:
| ID пайплайну | Cron-шлях | Обробник | Розклад |
|---|---|---|---|
subscription-expiry-check | /api/cron/subscription-expiry | runSubscriptionExpiryCheck | Щодня опівночі |
credit-balance-monthly | /api/cron/credit-balance-monthly | runCreditBalanceMonthly | Щогодини |
subscription-payment | /api/cron/subscription-payment | runSubscriptionPaymentCheck | Щодня о 2:00 |
solana-batch-payment | /api/cron/solana-batch-payment | runSolanaBatchPayment | Щодня о 3:00 |
nft-gate-expiry | /api/cron/nft-gate-expiry | runNftGateExpiry | Щодня о 4:00 |
Пайплайни запускаються через HTTP cron-завдання за cronPath. Обробники імпортуються з lib/processes/subscription/:
expiry-check.ts — позначає прострочені підписки як expired і знижує ролі користувачівcredit-balance-monthly.ts — списує щомісячну плату з кредитного балансуsubscription-payment.ts — обробляє рекурентні платежі Stripe/WayForPaysolana-nft-stubs.ts — пакетні перекази RING-токенів і закінчення терміну NFT-гейтуSubscriptionProviderModule у providers/<name>-subscription.tssubscription-conductor.ts у providerRegistry Mapring-config.json payment.gateways.<provider>SUBSCRIPTION_PROVIDERS у subscription-ledger-schema.tsgetMembershipPaymentOptions() у subscription-config.tslib/processes/subscription/
{
"payment": {
"cardPaymentProcessor": "wayforpay",
"supportedMethods": ["wayforpay", "credit_balance", "ring_token"],
"futureMethods": ["stripe", "paypal", "nft_gate"],
"gateways": {
"wayforpay": { "enabled": true, "feePercent": 2.5, "currency": "UAH" },
"stripe": { "enabled": false, "feePercent": 2.9, "feeFixedCents": 30, "currency": "USD" },
"credit_balance": { "enabled": true, "feePercent": 0, "currency": "USD" },
"ring_token": { "enabled": true, "feePercent": 0, "currency": "RING", "label": "Tokens" },
"paypal": { "enabled": false, "feePercent": 2.9, "feeFixedCents": 30, "currency": "USD" },
"nft_gate": { "enabled": false, "feePercent": 0, "currency": "RING", "label": "NFT Certificate" }
}
}
}
Membership upgrade / checkout
↓
lib/payments/subscription/subscription-conductor.ts
↓
Модулі провайдерів: stripe | wayforpay | credit_balance | ring_token | nft_gate | paypal
↓
subscription_ledger (PostgreSQL — провайдер-агностичний SSOT)
↓
Cron-пайплайни: expiry + payment + credit-balance + solana-batch + nft-gate
PAYMENT_MEMBERSHIP_PROCESSOR=wayforpay # Перевизначення карткового шлюзу для членства
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...| 2.9% |
| $0.30 |
| USD |
nft_gatenftGateSubscriptionProvider |
providers/subscription-provider-stubs.ts |
paypal | paypalSubscriptionProvider | providers/subscription-provider-stubs.ts |
Заглушки для WayForPay, NFT Gate та PayPal є заповнювачами; Stripe, Credit Balance та RING Token мають повні реалізації.
SSOT-колекція: subscription_ledger. Схема визначена в lib/payments/subscription/subscription-ledger-schema.ts (Zod).
Ключові поля:
| Поле | Тип | Опис |
|---|---|---|
id | string | ID рядка реєстру (sub_<ts>_<userIdSuffix>) |
user_id | string | ID користувача-власника |
provider | enum | stripe, wayforpay, credit_balance, ring_token, nft_gate, paypal |
gateway | string | Людино-читана мітка (напр. "Stripe", "WayForPay") |
method | enum | card, credit_balance, crypto, nft |
status | enum | active, expired, cancelled, suspended, grace_period |
amount | number | Ціна підписки (у мінорних одиницях) |
currency | string | Валюта білінгу |
gateway_fee_percent | number | Відсоткова комісія (напр. 2.9) |
gateway_fee_fixed | number | Фіксована комісія в мінорних одиницях (напр. 30 для Stripe) |
stripe_subscription_id | string? | Stripe-посилання (якщо провайдер Stripe) |
wayforpay_rec_token | string? | Рекурентний токен WayForPay |
solana_tx_signature | string? | Ончейн-підпис транзакції |
nft_mint_address | string? | Адреса мінту NFT-сертифіката |
start_time | number | Початок підписки (мс епохи) |
next_payment_due | number | Час наступного платежу |
failed_attempts | number | Послідовні невдачі платежу (макс 3 → авто expiring) |
auto_renew | boolean | Прапор автоподовження |
total_paid | string | Загалом сплачено за весь час |
payments_count | number | Кількість успішних платежів |
SubscriptionConductor (lib/payments/subscription/subscription-conductor.ts) надає:
| Операція | Сигнатура | Опис |
|---|---|---|
createSubscription | (input: CreateSubscriptionInput) → CreateSubscriptionResult | Маршрутизація до модуля провайдера, вставка рядка реєстру |
cancelSubscription | (userId, provider, gatewayRef?) → CancelSubscriptionResult | Скасування у провайдера + позначка рядків реєстру |
renewSubscription | (userId, provider, gatewayRef?) → RenewSubscriptionResult | Поновлення у провайдера + оновлення реєстру |
getSubscription | (userId) → SubscriptionLedgerRow | null | Остання активна підписка користувача |
getSubscriptions | (filter) → SubscriptionLedgerRow[] | Запит за користувачем, провайдером, статусом, методом, вікном оплати |
getStats | () → SubscriptionStats | Агреговані підрахунки за статусом, провайдером, методом |
calculateNetRevenue | (row) → { gross, fee, net, currency } | Чистий дохід на рядок |
| Метод | Шлях | Призначення | Авторизація |
|---|---|---|---|
POST | /api/membership/subscription/create | Створення підписки через conductor | Сесія |
GET | /api/membership/subscription/status | Статус підписки + баланс | Сесія |
POST | /api/membership/subscription/cancel | Скасування підписки | Сесія |
POST | /api/membership/payment/token | Обробка токен-платежу | Сесія |
GET | /api/admin/subscriptions | Список усіх підписок | Суперадмін |
GET | /api/admin/subscriptions/stats | Агрегована статистика | Суперадмін |
П'ять cron-пайплайнів зареєстровані в lib/processes/registry.ts у категорії membership:
| ID пайплайну | Cron-шлях | Обробник | Розклад |
|---|---|---|---|
subscription-expiry-check | /api/cron/subscription-expiry | runSubscriptionExpiryCheck | Щодня опівночі |
credit-balance-monthly | /api/cron/credit-balance-monthly | runCreditBalanceMonthly | Щогодини |
subscription-payment | /api/cron/subscription-payment | runSubscriptionPaymentCheck | Щодня о 2:00 |
solana-batch-payment | /api/cron/solana-batch-payment | runSolanaBatchPayment | Щодня о 3:00 |
nft-gate-expiry | /api/cron/nft-gate-expiry | runNftGateExpiry | Щодня о 4:00 |
Пайплайни запускаються через HTTP cron-завдання за cronPath. Обробники імпортуються з lib/processes/subscription/:
expiry-check.ts — позначає прострочені підписки як expired і знижує ролі користувачівcredit-balance-monthly.ts — списує щомісячну плату з кредитного балансуsubscription-payment.ts — обробляє рекурентні платежі Stripe/WayForPaysolana-nft-stubs.ts — пакетні перекази RING-токенів і закінчення терміну NFT-гейтуSubscriptionProviderModule у providers/<name>-subscription.tssubscription-conductor.ts у providerRegistry Mapring-config.json payment.gateways.<provider>SUBSCRIPTION_PROVIDERS у subscription-ledger-schema.tsgetMembershipPaymentOptions() у subscription-config.tslib/processes/subscription/
{
"payment": {
"cardPaymentProcessor": "wayforpay",
"supportedMethods": ["wayforpay", "credit_balance", "ring_token"],
"futureMethods": ["stripe", "paypal", "nft_gate"],
"gateways": {
"wayforpay": { "enabled": true, "feePercent": 2.5, "currency": "UAH" },
"stripe": { "enabled": false, "feePercent": 2.9, "feeFixedCents": 30, "currency": "USD" },
"credit_balance": { "enabled": true, "feePercent": 0, "currency": "USD" },
"ring_token": { "enabled": true, "feePercent": 0, "currency": "RING", "label": "Tokens" },
"paypal": { "enabled": false, "feePercent": 2.9, "feeFixedCents": 30, "currency": "USD" },
"nft_gate": { "enabled": false, "feePercent": 0, "currency": "RING", "label": "NFT Certificate" }
}
}
}
Membership upgrade / checkout
↓
lib/payments/subscription/subscription-conductor.ts
↓
Модулі провайдерів: stripe | wayforpay | credit_balance | ring_token | nft_gate | paypal
↓
subscription_ledger (PostgreSQL — провайдер-агностичний SSOT)
↓
Cron-пайплайни: expiry + payment + credit-balance + solana-batch + nft-gate
PAYMENT_MEMBERSHIP_PROCESSOR=wayforpay # Перевизначення карткового шлюзу для членства
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...