Мерчанты и платежи (BYOMA)

Framix работает по модели BYOMA — Bring Your Own Merchant Account: вы подключаете свой эквайринг, и деньги покупателей идут прямо на вашу кассу, а не на счёт Framix. Это упрощает жизнь и юридически (без посредничества по 54-ФЗ / лицензий PCI), и финансово (нет задержки между «оплачено клиентом» и «пришло вам»).

Framix забирает только комиссию платформы с оборота — она фиксируется в commerce_operation каждый раз, когда заказ переходит в paid, и считается отдельно от ежемесячных хостинг-списаний.

Поддерживаемые провайдеры

У одного workspace может быть несколько мерчантов одного провайдера (разные ИНН / бренды) — например, две Yookassa-кассы для двух юр.лиц. В UI чекаута / агента вы потом выбираете, какой именно мерчант обслуживает конкретного агента или сайт.

Подключение

/account/payments → «Подключить» → выберите провайдера.

В форме нужно ввести идентификаторы и секреты, которые провайдер выдаёт в своём ЛК:

• YooKassa — shopId + secretKey (опционально taxSystemCode в metadata для корректных фискальных чеков).
• CloudPayments — publicId + apiSecret, опционально webhookSecret.
• Tinkoff — terminalKey + password, опционально webhookSecret.
• Robokassa — merchantLogin + password1 + password2.

Все ключи хранятся зашифрованными AES-256-GCM в merchant_account.encryptedShopId / encryptedSecretKey. В API они никогда не возвращаются в plain — для UI используется maskToken (показывает первые/последние символы и звёздочки).

После создания мерчант можно протестировать (POST /api/merchants/test) — система делает пинг провайдера и проверяет, что ключи корректные.

Имя мерчанта (displayName)

Когда у workspace больше одного мерчанта одного провайдера, без названия они в UI неотличимы. Поэтому есть поле displayName — например, «YooKassa ИП Иванов», «YooKassa LLC Sweet Coffee». Это поле показывается в селекторах привязки.

Привязка к агенту и сайту

Когда платёж создаётся, нужно знать через какой мерчант проводить. Логика:

1. У товара ничего не настроено → берём мерчант из агента или сайта, через который идёт продажа.
2. У агента/сайта явная привязка → используем именно её.
3. У агента/сайта привязки нет, но в workspace один активный мерчант → используем его (legacy-режим).
4. Мерчантов больше одного, привязок нет → чекаут возвращает no_merchant_for_agent / no_merchant_for_project, UI просит выбрать.

Привязки:

• agent_merchant_account (M2M) — какой шлюз обслуживает оплату в чате этого агента.
• project_merchant_account (M2M) — какой шлюз обслуживает чекаут на этом сайте.

В UI это управляется на странице агента / на странице проекта в блоке «Платёжный шлюз».

Embedded YooKassa

Платёж YooKassa можно отдать клиенту двумя способами:

Framix включает embedded-виджет автоматически, когда YooKassa отдала confirmation_token. Никакой настройки не нужно — это работает out-of-box на host'е framix.app и на ваших custom-доменах.

В Telegram/VK по понятным причинам используется только redirect.

54-ФЗ и фискальные чеки

YooKassa требует receipt-объект для каждого платежа. Framix отправляет его автоматически:

• paymentSubject берётся из товара/услуги (commodity / service / job);
• vatCode — из товара/услуги;
• taxSystemCode — из merchant_account.metadata (заполняете при подключении кассы под свой налоговый режим).

Это автоматизирует чеки для УСН, самозанятых и плательщиков НДС. Корректность кодов — на вас: они должны соответствовать вашему режиму, иначе налоговая не примет.

Что хранится

Удаление и деактивация

• Деактивация (isActive=false) — мерчант остаётся, но в новых платежах не выбирается.
• Удаление — каскадно отвалятся привязки agent_merchant_account / project_merchant_account. Заказы с FK на этот merchant (commerce_order.merchantAccountId через ON DELETE RESTRICT) не дадут удалить мерчант, пока они есть.

Не удаляйте мерчант, если есть заказы со статусами pending_payment или awaiting_cod — webhook может прийти позже, и без мерчанта будет сложно сматчить.