docs: add yookassa payment integration design spec
This commit is contained in:
Kirill
@@ -0,0 +1,309 @@
|
||||
# YooKassa Payment Integration — Design
|
||||
|
||||
**Date:** 2026-05-20
|
||||
**Status:** approved
|
||||
|
||||
## Overview
|
||||
|
||||
Replace the current manual bank transfer payment flow (receipt upload + admin confirmation) with YooKassa (ЮKassa) online payment gateway integration using the redirect scenario.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Choice |
|
||||
|---|---|
|
||||
| Integration scenario | Redirect to YooKassa payment form |
|
||||
| Webhooks | Accept `payment.succeeded` and `payment.canceled` |
|
||||
| Receipts (54-ФЗ) | Send receipt data with order items |
|
||||
| Payment methods | Bank cards + SBP (Faster Payments System) |
|
||||
| Legacy manual method | Remove entirely |
|
||||
| Refunds via API | Not implemented (manual via YooKassa dashboard) |
|
||||
| Architecture pattern | Dedicated `lib/yookassa.js` module (Approach 2) |
|
||||
|
||||
---
|
||||
|
||||
## 1. Database Changes
|
||||
|
||||
### New model: `Payment`
|
||||
|
||||
```prisma
|
||||
model Payment {
|
||||
id String @id @default(cuid())
|
||||
orderId String
|
||||
order Order @relation(fields: [orderId], references: [id], onDelete: Cascade)
|
||||
yookassaPaymentId String @unique
|
||||
status String // pending | waiting_for_capture | succeeded | canceled
|
||||
amountCents Int
|
||||
currency String @default("RUB")
|
||||
confirmationUrl String?
|
||||
expiresAt DateTime?
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
@@index([orderId])
|
||||
@@index([yookassaPaymentId])
|
||||
}
|
||||
```
|
||||
|
||||
### Model `Order` — no changes
|
||||
|
||||
Existing `paymentMethod` (`online` | `on_pickup`) and status flow (`PENDING_PAYMENT` → `PAID`) remain unchanged.
|
||||
|
||||
---
|
||||
|
||||
## 2. Environment Variables
|
||||
|
||||
Add to `server/.env.example` and `server/.env`:
|
||||
|
||||
```bash
|
||||
YOOKASSA_SHOP_ID=123456
|
||||
YOOKASSA_SECRET_KEY=test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
For production (`SERVER_PUBLIC_URL` will be used for webhook URL construction):
|
||||
```bash
|
||||
YOOKASSA_SHOP_ID=123456
|
||||
YOOKASSA_SECRET_KEY=live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Server: `server/src/lib/yookassa.js`
|
||||
|
||||
Dedicated module isolating all YooKassa API interaction. Routes remain thin HTTP wrappers.
|
||||
|
||||
### Configuration
|
||||
|
||||
```js
|
||||
const config = {
|
||||
baseUrl: 'https://api.yookassa.ru/v3',
|
||||
shopId: process.env.YOOKASSA_SHOP_ID,
|
||||
secretKey: process.env.YOOKASSA_SECRET_KEY,
|
||||
}
|
||||
```
|
||||
|
||||
### Auth
|
||||
|
||||
HTTP Basic Auth: `Authorization: Basic base64(shopId:secretKey)`, set via `Idempotence-Key` header for POST requests.
|
||||
|
||||
### Exported functions
|
||||
|
||||
```
|
||||
createPayment({ order, orderItems, userEmail, idempotencyKey, returnUrl, clientIp }) → PaymentResponse
|
||||
```
|
||||
- `amount`: `order.totalCents` → `{ value: "1234.00", currency: "RUB" }`
|
||||
- `capture`: `true` (one-stage payment)
|
||||
- `confirmation`: `{ type: "redirect", return_url: returnUrl }`
|
||||
- `receipt`: `{ customer: { email: userEmail }, items: [...], tax_system_code: 1 }`
|
||||
- Each item: `description` (from `titleSnapshot`, max 128 chars), `quantity`, `amount` (unit price), `vat_code: 1`, `measure: "piece"`, `payment_subject: "commodity"`, `payment_mode: "full_prepayment"`
|
||||
- If `order.deliveryFeeCents > 0`: add a separate receipt item for delivery
|
||||
- `description`: `"Оплата заказа №{order.id}"`
|
||||
- `metadata`: `{ orderId: order.id }`
|
||||
- `payment_method_data`: not specified — YooKassa auto-selects from available methods (cards + SBP)
|
||||
- `client_ip`: forwarded from request
|
||||
- **Returns:** `{ paymentId, confirmationUrl, status, expiresAt }`
|
||||
|
||||
```
|
||||
getPayment(yookassaPaymentId) → PaymentResponse
|
||||
```
|
||||
- GET `/payments/{paymentId}` — fetch current payment status from YooKassa.
|
||||
- **Returns:** `{ id, status, paid, ... }`
|
||||
|
||||
```
|
||||
validateWebhook(body, headers) → { event, paymentObject }
|
||||
```
|
||||
- **Production only:** validate source IP against YooKassa IP ranges (`185.71.76.0/27`, `185.71.77.0/27`, `77.75.153.0/25`, `77.75.154.128/25`, `2a02:5180::/32`)
|
||||
- Skip IP check in test mode (when `secretKey` starts with `test_`)
|
||||
- Parse body: validate `type === "notification"`, extract `event` and `object`
|
||||
- **Returns:** parsed notification data
|
||||
- **Throws:** on validation failure
|
||||
|
||||
### Error handling
|
||||
|
||||
- 5xx: retry up to 3 times with exponential backoff (500ms, 1s, 2s)
|
||||
- 4xx: throw descriptive error (includes YooKassa error code and description)
|
||||
- Timeout: 10 seconds per request
|
||||
- Uses Node.js built-in `fetch` (Node 18+)
|
||||
|
||||
### Logging
|
||||
|
||||
Use `fastify.log` passed via context or a simple console-based approach. Log payment creation and webhook receipt at `info` level.
|
||||
|
||||
---
|
||||
|
||||
## 4. Server Routes
|
||||
|
||||
### 4a. `POST /api/me/orders/:id/pay` — Create payment (replaces existing)
|
||||
|
||||
**Auth:** `{ preHandler: [fastify.authenticate] }`
|
||||
|
||||
**Flow:**
|
||||
1. Find order by `id`, verify it belongs to `request.user.id`
|
||||
2. Validate: `status === PENDING_PAYMENT` AND `paymentMethod === 'online'` AND `deliveryFeeLocked === true`
|
||||
3. Check for existing active Payment (`status IN ('pending', 'waiting_for_capture')`):
|
||||
- If exists and not expired: return existing `confirmationUrl`
|
||||
- If exists but expired or canceled: proceed to create new one
|
||||
4. Generate `idempotencyKey`: `${orderId}-v1` (same key means same payment; if status check fails, append timestamp)
|
||||
5. Build `returnUrl`: `${CLIENT_PUBLIC_URL}/me/orders/${orderId}?paid=1`
|
||||
6. Call `yookassa.createPayment(...)`
|
||||
7. Save `Payment` to DB
|
||||
8. Return `{ confirmationUrl }`
|
||||
9. Emit event: `PAYMENT_CREATED`
|
||||
|
||||
**Error responses:**
|
||||
- `400`: order not in payable state
|
||||
- `409`: conflicting payment attempt (should be handled by idempotency)
|
||||
- `502`: YooKassa unavailable
|
||||
|
||||
### 4b. `GET /api/me/orders/:orderId/payment` — Check payment status
|
||||
|
||||
**Auth:** `{ preHandler: [fastify.authenticate] }`
|
||||
|
||||
**Flow:**
|
||||
1. Find latest `Payment` for the order
|
||||
2. If status is terminal (`succeeded`, `canceled`): return cached status
|
||||
3. Otherwise: call `yookassa.getPayment(yookassaPaymentId)`
|
||||
4. If status changed: update local `Payment` + transition `Order` if needed
|
||||
5. Return `{ status, paid }`
|
||||
|
||||
### 4c. `POST /api/webhooks/yookassa` — Receive YooKassa notifications
|
||||
|
||||
**Auth:** None (public endpoint, validated by IP + request signature)
|
||||
|
||||
**Flow:**
|
||||
1. Parse body and headers
|
||||
2. Call `yookassa.validateWebhook(body, headers)` — validates IP on production
|
||||
3. Find `Payment` by `yookassaPaymentId = object.id`
|
||||
4. Handle event:
|
||||
- `payment.succeeded`:
|
||||
- Update `Payment.status = 'succeeded'`
|
||||
- Transition `Order` from `PENDING_PAYMENT` to `PAID`
|
||||
- Emit `PAYMENT_STATUS_CHANGED` event → notification system
|
||||
- `payment.canceled`:
|
||||
- Update `Payment.status = 'canceled'`
|
||||
- Order stays `PENDING_PAYMENT` (user can retry)
|
||||
5. Return `200 OK`
|
||||
|
||||
### 4d. Remove old endpoint
|
||||
|
||||
The existing `POST /api/me/orders/:id/pay` (multipart receipt upload) is completely removed.
|
||||
|
||||
---
|
||||
|
||||
## 5. Client Changes
|
||||
|
||||
### 5a. `OrderPaymentSection` (features/order-payment)
|
||||
|
||||
- **State `PENDING_PAYMENT` + `deliveryFeeLocked=true` + `paymentMethod=online`:**
|
||||
- Show "Оплатить" button
|
||||
- On click: call `createOrderPayment(orderId)`, get `confirmationUrl`, redirect: `window.location.href = confirmationUrl`
|
||||
- **State `PENDING_PAYMENT` + `deliveryFeeLocked=false`:** unchanged (waiting for delivery fee adjustment)
|
||||
- **State `PAID`:** show "Оплачено" badge, hide payment button
|
||||
- **State `paymentMethod=on_pickup`:** unchanged (message about paying at pickup)
|
||||
|
||||
### 5b. Remove `PaymentDialog`
|
||||
|
||||
Delete `PaymentDialog.tsx` and all related code (manual payment instructions, receipt upload form). Remove `PAYMENT_TRANSFER_INSTRUCTIONS_PLAIN` constant if present.
|
||||
|
||||
### 5c. Return URL handling (OrderDetailPage)
|
||||
|
||||
When order page loads with `?paid=1` query param:
|
||||
1. Call `getOrderPaymentStatus(orderId)`
|
||||
2. Show result toast/alert:
|
||||
- `paid === true`: "Оплата прошла успешно"
|
||||
- `paid === false` + payment pending: "Ожидаем подтверждения оплаты"
|
||||
- `canceled`: "Оплата отменена, вы можете попробовать снова"
|
||||
|
||||
### 5d. API client additions (shared/api or entities/order)
|
||||
|
||||
```ts
|
||||
// New API endpoints to add to the client apiClient:
|
||||
createOrderPayment(orderId: string): Promise<{ confirmationUrl: string }>
|
||||
getOrderPaymentStatus(orderId: string): Promise<{ status: string, paid: boolean }>
|
||||
```
|
||||
|
||||
### 5e. Shared constants
|
||||
|
||||
Remove `online` from `PAYMENT_METHODS` if it was only used for distinction, or keep it since YooKassa IS the online payment. The constant stays as-is.
|
||||
|
||||
---
|
||||
|
||||
## 6. Edge Cases & Error Handling
|
||||
|
||||
### Payment creation failures
|
||||
|
||||
| Scenario | Handling |
|
||||
|---|---|
|
||||
| YooKassa unavailable (5xx) | Retry 3x with backoff, then show user error "Платёжный сервис временно недоступен, попробуйте позже" |
|
||||
| Invalid credentials (401) | Log error, show "Ошибка конфигурации платежей" |
|
||||
| Duplicate idempotency key | YooKassa returns existing payment — reuse it |
|
||||
|
||||
### Status synchronization
|
||||
|
||||
- **Primary:** webhook `payment.succeeded` triggers order → `PAID` transition
|
||||
- **Fallback:** user returning via `return_url` triggers `GET /api/me/orders/:orderId/payment` which syncs via API
|
||||
- **Stale payments:** no periodic cron needed initially; the fallback on page load is sufficient
|
||||
|
||||
### Payment expiration
|
||||
|
||||
YooKassa cancels payments after ~1 hour (for one-stage with `capture: true`). Webhook `payment.canceled` updates local state.
|
||||
|
||||
### User closes browser after paying, before return
|
||||
|
||||
Webhook handles this — order transitions to `PAID` without user action. On next visit, order shows as paid.
|
||||
|
||||
### Retry after cancellation
|
||||
|
||||
User can click "Оплатить" again. New `Payment` record created with new `yookassaPaymentId`. Old payment remains in DB with `canceled` status.
|
||||
|
||||
### Idempotency
|
||||
|
||||
- Key format: `${orderId}-v1` — if user clicks "Оплатить" twice quickly, YooKassa returns the same payment (idempotency protection)
|
||||
- If payment exists and is terminal (canceled/expired), generate new key: `${orderId}-v${retryCount}`
|
||||
|
||||
---
|
||||
|
||||
## 7. Files Changed / Created / Deleted
|
||||
|
||||
### Created
|
||||
- `server/src/lib/yookassa.js` — YooKassa API client module
|
||||
- `server/prisma/migrations/*_add_payment.sql` — migration for Payment model
|
||||
|
||||
### Modified
|
||||
- `server/prisma/schema.prisma` — add `Payment` model
|
||||
- `server/src/routes/user-payments.js` — rewrite to use YooKassa
|
||||
- `server/src/index.js` — register webhook route
|
||||
- `server/.env.example` — add YooKassa env vars
|
||||
- `client/src/features/order-payment/OrderPaymentSection.tsx` — redirect to YooKassa instead of manual dialog
|
||||
- `client/src/pages/order/OrderDetailPage.tsx` — handle `?paid=1` return URL
|
||||
- `client/src/shared/api/` or `entities/order/` — add new API methods
|
||||
|
||||
### Deleted
|
||||
- `client/src/features/order-payment/PaymentDialog.tsx` — manual payment dialog
|
||||
- Any related payment instructions constants
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing
|
||||
|
||||
### Server tests (`server/src/__tests__/` or `server/src/lib/__tests__/`)
|
||||
|
||||
- `yookassa.test.js` — unit tests for `createPayment`, `getPayment`, `validateWebhook` with mocked `fetch`
|
||||
- `user-payments.test.js` — integration tests for `POST /api/me/orders/:id/pay` with mocked YooKassa module
|
||||
- Webhook route test — validate IP check, event handling, order transition
|
||||
|
||||
### Client tests (`client/src/features/order-payment/__tests__/`)
|
||||
|
||||
- `OrderPaymentSection.test.tsx` — test button shows/hides based on order state, redirect on click
|
||||
- Remove `PaymentDialog.test.tsx` if it exists
|
||||
|
||||
---
|
||||
|
||||
## 9. Migration & Rollout
|
||||
|
||||
1. Add env vars to `.env`
|
||||
2. Run Prisma migration: `prisma migrate dev --name add_payment`
|
||||
3. Deploy server changes first (new routes + webhook)
|
||||
4. Deploy client changes (redirect behavior)
|
||||
5. Configure webhook in YooKassa dashboard: `{SERVER_PUBLIC_URL}/api/webhooks/yookassa`
|
||||
6. Test with YooKassa test credentials
|
||||
7. Switch to live credentials after successful testing
|
||||
Reference in New Issue
Block a user