---
title: "Интеграция платёжного шлюза"
description: "Руководство оператора — PaymentConductor, WayForPay, Stripe, PayPal и внутренний credit для store, membership, news, пополнения wallet и card jars публичных пулов"
locale: "ru"
---
# Интеграция платёжного шлюза

  Ring проводит card- и credit-потоки через **PaymentConductor** — один ledger (`payment_transactions`), один webhook-диспетчер, процессоры из конфига. Операторы настраивают env и кабинеты PSP; разработчики читают [PaymentConductor architecture](/docs/architecture/payment-conductor.md). Card chip-in DAO jar используют purpose **`public_pool_contribution`** ([Public Pools](/docs/features/public-pools.md)) — не hosted «donation»-продукты WayForPay/Stripe/PayPal.

> **Info**
> Используйте вкладки **Founder** / **Developer** в боковом меню документации, чтобы фильтровать эту страницу.

  
- **[PaymentConductor feature](/docs/features/payment-conductor.md)** — Purposes, rails, обзор env

  
- **[Public Pools & DAO Jars](/docs/features/public-pools.md)** — Desk-oracle card jar, комиссии, escrow gate

  
- **[Architecture deep dive](/docs/architecture/payment-conductor.md)** — Handlers, ledger, idempotency, API-маршруты

  
- **[WayForPay integration](/docs/features/wayforpay-integration.md)** — Env SSOT, HMAC, пароль regularApi

```mermaid
sequenceDiagram
  participant U as User
  participant R as Ring API
  participant PC as PaymentConductor
  participant PSP as WayForPay / Stripe
  participant DB as payment_transactions

  U->>R: Checkout / upgrade / promotion / top-up / jar chip-in
  R->>PC: createCheckout(purpose)
  PC->>DB: createPending(orderReference)
  PC->>PSP: redirect URL
  PSP->>U: Hosted payment
  PSP->>R: POST webhook
  R->>PC: dispatch webhook
  PC->>DB: mark paid
  PC->>R: purpose handler fulfills
```

## Payment purposes

| Purpose | Typical use | Handler |
|---------|-------------|---------|
| `store_order` | Checkout multi-vendor store | `conductor/handlers/store-order.ts` |
| `membership_upgrade` | SUBSCRIBER → MEMBER | `conductor/handlers/membership-upgrade.ts` |
| `news_promotion` | Платная промоция News Kingdom | `conductor/handlers/news-promotion.ts` |
| `wallet_topup` | Пополнение wallet credit (card) | `conductor/handlers/wallet-topup.ts` |
| `public_pool_contribution` | Public pool / DAO jar card или PayPal | `conductor/handlers/public-pool-contribution.ts` |

**Processors:** WayForPay (default), Stripe, internal credit, native token, **PayPal** (Orders для store/wallet/jars; Subscriptions v1 для recurring membership — см. [SubscriptionConductor](/docs/features/subscriptions.md)).

**Rails:** `merchant_redirect` · `credit_balance` (`PAYMENT_STORE_ALLOW_CREDIT`) · `native_token` (`PAYMENT_STORE_ALLOW_TOKEN`).

Примените `data/migrations/004_payment_transactions.sql` до production-платежей.

### For founders

## Настройка для оператора

### Переменные окружения

{`PAYMENT_DEFAULT_PROCESSOR=wayforpay
PAYMENT_STORE_PROCESSOR=wayforpay
PAYMENT_MEMBERSHIP_PROCESSOR=wayforpay
PAYMENT_NEWS_PROCESSOR=wayforpay
PAYMENT_WALLET_TOPUP_PROCESSOR=wayforpay
# Optional: PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR=wayforpay
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret
WAYFORPAY_MERCHANT_PASSWORD=your_password
WAYFORPAY_DOMAIN=ring-platform.org
WAYFORPAY_API_URL=https://api.wayforpay.com/api
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYMENT_FIAT_CURRENCY=USD
PAYMENT_STORE_ALLOW_CREDIT=true
PAYMENT_STORE_ALLOW_TOKEN=false
NEXT_PUBLIC_PAYMENT_STORE_ALLOW_PAYPAL=false
# PAYPAL_MODE=sandbox
# PAYPAL_CLIENT_ID=
# PAYPAL_CLIENT_SECRET=
# PAYPAL_WEBHOOK_ID=`}

> **Warning**
> **Нет `WAYFORPAY_MERCHANT_ID`.** Используйте `WAYFORPAY_MERCHANT_ACCOUNT`. Задайте `WAYFORPAY_DOMAIN` на одобренный домен вашего клона (для этого продукта: `ring-platform.org`). `WAYFORPAY_MERCHANT_PASSWORD` обязателен для recurring / `regularApi`.

### URL webhook (зарегистрируйте в кабинете PSP)

Замените host на домен вашего клона:

| Provider | Service URL |
|----------|-------------|
| WayForPay | `https://ring-platform.org/api/payments/wayforpay/webhook` |
| Stripe | `https://ring-platform.org/api/payments/stripe/webhook` |

> **Warning**
> **Нужен публичный HTTPS.** WayForPay / Stripe не могут POST на `localhost`. Локальные card-тесты откроют страницу PSP, но **credit не settle'ится**, пока `serviceUrl` недоступен (tunnel или staging). Ring эмитит `returnUrl` на каждый запрос — **не** нужна статическая thank-you страница в кабинете WayForPay. См. [WayForPay](/docs/features/wayforpay-integration.md).

  Устаревшие пути `/api/payments/wayforpay/callback`, `/success`, `/failure` — **не реализованы**.

Устаревшие aliases (ещё работают — мигрируйте, когда удобно):

- `/api/store/payments/wayforpay/webhook`
- `/api/news/promotion/wayforpay-webhook`

### Чеклист перед запуском

Миграция `004_payment_transactions.sql` применена на production Postgres.

`PAYMENT_*` и учётные данные WayForPay / Stripe в secrets manager (никогда не коммитьте `.env.local`).

Зарегистрированы канонические webhook URL; `WAYFORPAY_DOMAIN` совпадает с одобренным merchant domain.

Staging smoke: store checkout, card upgrade membership, news promotion (если используется), wallet credit top-up.

После go-live: мониторьте `payment_transactions` на зависшие строки `pending` / `redirected`; история membership / wallet top-up — Admin → user → вкладка Payments.

### For developers

## Маршруты и модули

| Route file | Method | Role |
|------------|--------|------|
| `app/api/payments/wayforpay/webhook/route.ts` | POST | `dispatchWayForPayWebhook` |
| `app/api/payments/stripe/webhook/route.ts` | POST | `dispatchStripeWebhook` |
| `app/api/store/payments/wayforpay/route.ts` | POST | Store redirect через `PaymentConductor` (`store_order`) |
| `app/api/store/payments/credit/route.ts` | POST | Checkout internal credit |
| `app/api/store/payments/[orderId]/status/route.ts` | GET | Poll статуса заказа |
| `app/api/admin/users/[id]/payments/route.ts` | GET | Вкладка Admin Payments (`listByUserId`) |

WayForPay маршрутизирует по префиксу `orderReference` (`store_`, `membership_`, `news-promo-…`, `wallettopup_`) — см. `lib/payments/conductor/webhook-dispatcher.ts` и `lib/payments/order-reference.ts`.

### Настройка PSP — WayForPay

Создайте merchant-аккаунт на [wayforpay.com](https://wayforpay.com) — KYC, зафиксируйте **merchant account**, **secret key**, **merchant password**, одобренный **domain**.

Задайте env Ring из `env.local.template` (также зеркалится в `docker.env.template` / `docker-compose.template.yml`).

Cabinet **service URL**: `https:///api/payments/wayforpay/webhook`.

Staging: миграция `004` → тест checkout / membership / wallet top-up → подтвердите `payment_transactions` + fulfillment.

### Настройка PSP — Stripe

Создайте аккаунт на [stripe.com](https://stripe.com); получите test или live API keys.

{`PAYMENT_DEFAULT_PROCESSOR=stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...`}

Dashboard → Webhooks → endpoint `https:///api/payments/stripe/webhook`. Подпишитесь на `checkout.session.completed` (и события, которые обрабатывает ваш processor).

## Связанное

  
- **[Payments feature](/docs/features/payments.md)** — Поток membership и обзор

  
- **[Store API](/docs/api/store.md)** — Checkout через PaymentConductor `store_order`

  
- **[Wallet](/docs/features/wallet.md)** — Live WayForPay credit top-up

  
- **[Migrations](/docs/getting-started/migrations.md)** — Порядок применения, включая миграцию 004