Платежный агент: два сценария

ПА принимает рубли от клиента ЦСО и рассчитывается с зарубежным партнёром. Эта страница — каркас рассказа. Живые поручения после npm run demo:seed смотрите в Ops Admin.

Кто есть кто

ЦСОКонсьерж-сервис. Создаёт поручение, передаёт реквизиты клиенту.
ПАПлатежный агент. Курс, УИН, выплата партнёру, журнал событий.
КлиентПлатит рубли на счёт ПА по УИН или ссылке.
Банк / формаВыписка по УИН (8.1) или оплата картой на форме (8.2).
ПартнёрОтель, ресторан, трансфер. Подтверждает услугу вебхуком.

8.1 INVOICE — инвойс и SWIFT

Партнёр выставил инвойс в своей валюте. Клиент платит рубли на счёт ПА, ПА конвертирует и отправляет SWIFT MT103.

sequenceDiagram participant CSO as ЦСО participant PA as ПА participant Client as Клиент participant BankNR as Банк-нерезидент participant Partner as Партнёр CSO->>PA: POST /v1/orders (scenario INVOICE) PA-->>CSO: 201 pa_order_id, DRAFT CSO->>PA: PATCH /assign CSO->>PA: POST /payment-details PA->>PA: Фиксация курса, генерация УИН PA-->>CSO: Реквизиты ПА в рублях + УИН, AWAITING_PAYMENT Client->>PA: Перевод рублей на счёт ПА (УИН в назначении) Note over PA: Выписка банка счёта ПА → POST /v1/callbacks/bank/statement PA->>PA: Сверка по УИН, CLIENT_PAID PA->>BankNR: Покупка валюты, FX_EXECUTED BankNR->>Partner: SWIFT MT103 на IBAN партнёра PA-->>CSO: order.partner_paid + подтверждение SWIFT Partner->>PA: POST /v1/callbacks/partner/service-confirmed PA-->>CSO: order.status_changed COMPLETED

8.2 PAYMENT_LINK — форма партнёра

Инвойса нет: у партнёра платёжная страница. Клиент платит рубли ПА, ПА оплачивает форму иностранной картой.

sequenceDiagram participant CSO as ЦСО participant PA as ПА participant Client as Клиент participant Form as Форма партнёра participant Partner as Партнёр CSO->>PA: POST /v1/orders (scenario PAYMENT_LINK) CSO->>PA: PATCH /assign CSO->>PA: POST /payment-details PA-->>CSO: Платёжная ссылка в рублях, AWAITING_PAYMENT Client->>PA: Оплата рублями по ссылке PA->>PA: CLIENT_PAID, конвертация в валюту PA->>Form: Оплата иностранной картой Form-->>PA: Код авторизации и чек PA-->>CSO: order.partner_paid Partner->>PA: Подтверждение услуги PA-->>CSO: COMPLETED

Воронка статусов

Переходы атомарны и пишутся в журнал. Любой шаг вне схемы — 409.

stateDiagram-v2 [*] --> DRAFT DRAFT --> IN_PROGRESS: взято в работу DRAFT --> PENDING_DOCS: запрошены документы PENDING_DOCS --> IN_PROGRESS: документы получены IN_PROGRESS --> PENDING_DOCS: запрошены документы IN_PROGRESS --> FX_FIXED: курс зафиксирован FX_FIXED --> AWAITING_PAYMENT: реквизиты выданы AWAITING_PAYMENT --> CLIENT_PAID: поступили рубли CLIENT_PAID --> FX_EXECUTED: конвертация FX_EXECUTED --> PARTNER_PAID: партнёр оплачен PARTNER_PAID --> COMPLETED: услуга подтверждена DRAFT --> REJECTED PENDING_DOCS --> REJECTED IN_PROGRESS --> REJECTED FX_FIXED --> REJECTED AWAITING_PAYMENT --> REJECTED CLIENT_PAID --> REFUND_INITIATED FX_EXECUTED --> REFUND_INITIATED PARTNER_PAID --> REFUND_INITIATED REFUND_INITIATED --> REFUNDED DRAFT --> EXPIRED PENDING_DOCS --> EXPIRED IN_PROGRESS --> EXPIRED FX_FIXED --> EXPIRED AWAITING_PAYMENT --> EXPIRED

Сценарий рассказа

Дев-стенд: meafdev.ru. После рестарта API снова npm run demo:seed (данные в памяти процесса).

Ops Admin Dashboard Поручения Webhooks / DLQ API docs Partner Как пользоваться

Вход Ops: admin@meafcoop.com / Admin123!

  1. Dashboard — воронка «как в проде»: ждут оплату, ждут документы, ждут ваучер, закрытые, возврат. Через ~30 с на Webhooks появится DLQ (вебхуки партнёров на example.com не доставляются).
  2. CSO-DEMO-HOTEL-ROMA — полный 8.1 до COMPLETED. Карточка: УИН, SWIFT, чек, журнал событий.
  3. CSO-DEMO-ISTANBUL-DINNER — полный 8.2. Отличие: выплата картой на форме, не MT103 (auth code на карточке).
  4. CSO-DEMO-AWAIT-UIN — AWAITING_PAYMENT. На карточке УИН и р/с: «это отдаём клиенту». Для 8.2 ссылка ПА открывается как /pay/{id}.
  5. CSO-DEMO-NEED-PASSPORT — PENDING_DOCS. Очередь оператора.
  6. CSO-DEMO-DRAFT-DUBAI — DRAFT. «Assign на себя», затем «Выдать реквизиты» вживую (роль Operator / Superadmin).
  7. CSO-DEMO-WAIT-VOUCHER — PARTNER_PAID: деньги ушли, услуги ещё нет. Кнопка «Услуга подтверждена» закрывает в COMPLETED.
  8. CSO-DEMO-REJECTED и CSO-DEMO-REFUNDED — отказ до оплаты и возврат после выплаты.
  9. CSO-DEMO-EXPIRED — просроченный deadline; cron раз в минуту переводит в EXPIRED.

Портфель сида

order_idСтатусСценарийПартнёр
CSO-DEMO-HOTEL-ROMACOMPLETEDINVOICEPARTNER-777
CSO-DEMO-ISTANBUL-DINNERCOMPLETEDPAYMENT_LINKPARTNER-301
CSO-DEMO-DUBAI-TRANSFERCOMPLETEDINVOICEPARTNER-512
CSO-DEMO-AWAIT-UINAWAITING_PAYMENTINVOICEPARTNER-777
CSO-DEMO-AWAIT-LINKAWAITING_PAYMENTPAYMENT_LINKPARTNER-301
CSO-DEMO-NEED-PASSPORTPENDING_DOCSINVOICEPARTNER-777
CSO-DEMO-DRAFT-DUBAIDRAFTINVOICEPARTNER-512
CSO-DEMO-IN-PROGRESSIN_PROGRESSPAYMENT_LINKPARTNER-301
CSO-DEMO-WAIT-VOUCHERPARTNER_PAIDINVOICEPARTNER-777
CSO-DEMO-REJECTEDREJECTEDINVOICEPARTNER-512
CSO-DEMO-REFUNDEDREFUNDEDINVOICEPARTNER-777
CSO-DEMO-EXPIREDEXPIREDPAYMENT_LINKPARTNER-301