---
title: "Членство та кредити"
description: "Рівні членства Ring і кредитний баланс — драбина з шести ролей, ціноутворення апгрейду в RING з desk oracle, checkout-рейки PaymentConductor і реєстр підписок"
locale: "uk"
---
# Членство та кредити

> **Info**
> Використовуйте вкладки **Founder** / **Developer** у бічній панелі, щоб відфільтрувати цю сторінку. Користувацькі сценарії рендеряться на `/membership`; ця стаття документує рівні, ціни та платіжні рейки.

Членство — як клон Ring розрізняє рівні спільноти та монетизує доступ. Драбина ролей — SSOT (`features/auth/user-role.ts`), ціноутворення апгрейду керується конфігом (`lib/membership/pricing.ts`), і кожен платіж — картка, кредитний баланс, PayPal або нативний токен — проходить через PaymentConductor.

## Драбина ролей (SSOT)

| Role | Meaning |
|------|---------|
| `visitor` | Не автентифікований, лише перегляд |
| `subscriber` | Платний базовий підписник — базовий доступ до спільноти |
| `member` | Підвищений статус із ширшим доступом |
| `confidential` | Доступ до конфіденційних ресурсів |
| `admin` | Адмін платформи |
| `superadmin` | Адмін платформи найвищого рівня |

Апгрейди переводять користувача з `subscriber` → `member`. Конфіг рівня `confidential` явно вимагає роль confidential.

### For founders

## Чому це важливо для вашого клону

- **Монетизуйте доступ** платним рівнем member, тоді як visitors і subscribers зберігають базовий доступ.
- **Один checkout, багато рейок.** PaymentConductor об'єднує картку, кредитний баланс, PayPal і нативний токен — той самий checkout-рушій, що й у магазині.
- **Передбачувані ціни в RING.** Місячний апгрейд за замовчуванням — **1 RING** (`membership.ring.memberUpgradeAmount`), річний дає **20% знижки** від monthly × 12, а живі котирування йдуть через desk oracle, щоб сума рахунку збігалася з котируванням.
- **Кредитний баланс — основна деномінація.** Понад 10 кредитних одиниць (`MEMBERSHIP_DESK_CREDIT_HINT_MIN`) UI підказує обмін на Token Desk замість купівлі кредиту.

### Чеклист оператора

1. Підтвердіть платіжні процесори в PaymentConductor (WayForPay / Stripe / PayPal на клон).
2. Перегляньте суми `membership.ring` і конфіг рівня `member` у `ring-config.json`.
3. Прогоніть один реальний апгрейд на кожну рейку (картка, кредит, токен) у staging-клоні перед go-live.

### For developers

## Модулі ціноутворення (перевірено)

| Module | Role |
|--------|------|
| `lib/membership/pricing.ts` | Sync-хелпери — суми RING за період, річна знижка 20%, підказка credit desk |
| `lib/membership/pricing-live.ts` | Лише серверні живі desk-котирування через `getNativeTokenToMainCurrencyRate` |
| `lib/payments/conductor/handlers/membership-upgrade.ts` | Обробка purpose апгрейду |
| `lib/payments/conductor/handlers/membership-upgrade-stripe.ts` / `-paypal.ts` | Рейки апгрейду під конкретного провайдера |
| `lib/payments/payment.config.ts` | Purpose `membership_upgrade` → `PAYMENT_MEMBERSHIP_PROCESSOR` |

## API-поверхня

| Route | Methods | Purpose |
|-------|---------|---------|
| `/api/membership/payment/card` | POST, GET | Картковий checkout для членства |
| `/api/membership/payment/credit` | POST, GET | Шлях оплати з кредитного балансу |
| `/api/membership/payment/paypal` | POST, GET | Checkout через PayPal |
| `/api/membership/payment/token` | POST, GET | Оплата нативним токеном |
| `/api/membership/subscription/create` | POST | Створити підписку |
| `/api/membership/subscription/status` | GET | Прочитати статус підписки |
| `/api/membership/subscription/cancel` | POST, GET | Скасувати підписку |

## Істина реєстру

**Куди потрапляють гроші**

Платні апгрейди пишуться в **реєстр підписок** (`subscription_ledger`) — провайдер `credit_balance` позначає поновлення, оплачені кредитом (`next_payment_due` індексується в `data/schema.sql`). Сам кредит живе в записі користувача (`users.data.credit_balance`), а wallet-транзакції слугують аудитом (`features/wallet/services/credit-balance-service.ts`).

**Білінгові періоди**

`MembershipBillingPeriod = 'monthly' | 'yearly'`. Річна вартість = `annualUpgradeAmount`, якщо задано, інакше monthly × 12 × 0.8 (знижка 20%). Форма рівня: `MemberTierConfig { amount, currency, description, duration }`.

## Повʼязана документація

  
- [features/wallet-conductor](/docs/features/wallet-conductor.md) — Deep-dive: кредитний реєстр і двоставковий SSOT, у який осідають платежі за членство.

  
- [features/payment-conductor](/docs/features/payment-conductor.md) — Depends-on: картка, PayPal і токен-рейки всі йдуть через PaymentConductor.

  
- [features/subscriptions](/docs/features/subscriptions.md) — Same-workflow: життєвий цикл поновлення та обробка скасування.

  
- [architecture/data-model](/docs/architecture/data-model.md) — See-also: як credit_balance і реєстр підписок живуть у JSONB-схемі.