Payment Orchestrator

Тема

03.16 MVP Release And Merchant Transition ​

Статус: черновик для обсуждения

1. Назначение документа ​

Этот документ описывает release / transition flow для первого merchant-а в MVP.

Цель документа - зафиксировать, как merchant будет постепенно переходить со старой системы на новую систему.

Важно: в MVP не строится сложная technical canary / rollback / feature flag system.

Переход происходит operationally:

  • merchant продолжает работать на v1;
  • merchant получает новую integration documentation и endpoints v2;
  • merchant постепенно переводит методы на v2;
  • после прекращения traffic по старому методу выполняется migration historical transactions.

2. Основной принцип перехода ​

Первый merchant не переводится на новую систему одним большим переключением.

Переход выполняется постепенно:

  • merchant имеет несколько payment methods;
  • каждый payment method переводится отдельно;
  • merchant сам начинает использовать новые endpoints, когда готов;
  • HoE задает merchant-у конкретные сроки перехода.

Пример:

text
Step 1: merchant переводит Cards на /api/v2/deposit
Step 2: merchant переводит Apple Pay на /api/v2/deposit
Step 3: merchant переводит BLIK на /api/v2/deposit
...

Старая система остается активной, пока merchant еще отправляет туда traffic.

3. Кто принимает решение ​

Решение о том, что merchant / payment method можно переводить на новую систему, принимает Product Owner.

MVP acceptance выполняет Product Owner.

Merchant не переключается технической кнопкой в Back Office. Merchant начинает отправлять requests на новые endpoints самостоятельно.

4. Что получает merchant ​

Перед переходом merchant должен получить:

  • public Merchant API documentation в public documentation portal;
  • stg/prod base URLs;
  • endpoint /api/v2/deposit;
  • правила request signing;
  • HMAC signing examples на нескольких programming languages;
  • описание create deposit request/response;
  • описание error response;
  • список transaction statuses;
  • список merchant-facing error codes;
  • описание merchant webhook payload;
  • описание webhook signing;
  • webhook signature validation examples;
  • sandbox/test provider flow;
  • test provider expected status simulation;
  • сроки перехода на новую версию.

Postman collection и OpenAPI spec не являются обязательными merchant-facing deliverables для MVP.

Owner merchant documentation:

text
Product Owner

5. Minimum checks before live traffic ​

Перед тем как merchant начнет отправлять live traffic по конкретному payment method в v2, должны быть проверены:

  • merchant создан в новой системе;
  • brand создан;
  • API key создан;
  • payment method активен;
  • routing configuration опубликована;
  • required MASTER MID / MASTER MID GROUP configured;
  • required SUB MID / SUB MID GROUP / SUB MID AGGREGATOR configured;
  • webhook URLs проверены;
  • provider callback route проверен;
  • test deposit через Back Office выполнен успешно;
  • test deposit через Merchant API выполнен успешно, если это возможно перед live traffic;
  • transaction видна в Back Office;
  • transaction timeline понятен;
  • merchant webhook доставлен успешно.

Это не отдельный standalone checklist и не отдельный checklist UI в MVP.

Эти checks должны быть частью release tasks / UAT demo сценариев.

6. Test transaction ​

Перед live traffic нужно выполнить test transaction.

Минимально:

  • test deposit из Back Office;
  • при возможности test deposit через Merchant API;
  • test provider status simulation;
  • проверка hosted payment URL;
  • проверка hosted redirect URL test provider-а;
  • проверка provider execution;
  • проверка provider callback;
  • проверка merchant webhook;
  • проверка transaction visibility in Back Office.

7. Не храним migrated-to-v2 marker ​

В MVP не нужно хранить дату/время переключения merchant / payment method на v2.

В MVP не нужно показывать в Back Office, что merchant / payment method уже migrated to v2.

Причина:

  • переход выполняется через изменение integration behavior на стороне merchant;
  • merchant может некоторое время использовать v1 и v2 параллельно для разных methods;
  • отдельный migration status создаст лишнюю product complexity.

8. Rollback ​

В MVP не нужна отдельная rollback system.

Пока merchant постепенно переходит на v2, v1 продолжает работать.

Если по конкретному method merchant еще не перешел на v2, он продолжает использовать v1.

Если merchant начал использовать v2 и возникла operational problem, возврат означает, что merchant вручную возвращает traffic на старый v1 endpoint, если это еще возможно.

Back Office rollback button / feature flag / emergency pause не нужны в MVP.

Отдельная rollback procedure document не нужна для MVP.

9. Когда выполняется historical migration ​

Historical transaction migration выполняется после того, как merchant перестал отправлять traffic по старому method в v1.

Flow:

  1. Merchant переводит конкретный payment method на v2.
  2. Merchant перестает отправлять traffic по этому method в v1.
  3. Platform запускает temporary migration tool.
  4. Historical transactions из v1 переносятся в v2 Back Office.
  5. Migrated transactions marked as legacy.
  6. Merchant/support/platform могут видеть historical transactions в новом Back Office.

Migration не является частью live traffic switching.

Migration не отправляет webhooks и не запускает processing.

10. Удаление v1 ​

Старая версия остается активной, пока merchant еще использует v1 endpoints.

Когда merchantы полностью перестают использовать v1 endpoints:

  • historical transactions переносятся в новую систему;
  • команда может планировать удаление / отключение v1 functionality;
  • temporary migration tool может быть удален после завершения migration phase.

Удаление v1 не является отдельной feature в MVP, но должно быть учтено как финальный operational outcome.

11. MVP acceptance ​

MVP считается успешно принятым, если:

  • Product Owner принял MVP;
  • public merchant documentation portal готов;
  • первый merchant может создать live deposit через /api/v2/deposit;
  • хотя бы один payment method успешно работает на v2;
  • hosted payment URL возвращается merchant-у;
  • customer может завершить payment flow;
  • provider callback обработан;
  • merchant webhook отправлен и доставлен;
  • transaction видна в Back Office;
  • transaction details отображают понятный routing path;
  • transaction timeline позволяет расследовать full flow;
  • platform/support могут понять, какой route был выбран и почему;
  • merchant user может видеть доступные ему transaction details;
  • legacy transaction migration может быть выполнена после прекращения v1 traffic по method;
  • обязательные UAT/demo scenarios пройдены;
  • load test выполнен и принят.

Required UAT/demo scenarios:

  • full demo from merchant creation to successful deposit;
  • failed deposit;
  • fallback routing;
  • velocity rejection;
  • manual transaction correction;
  • webhook retry;
  • manual webhook resend;
  • duplicate provider callback handling;
  • ignored provider callback handling;
  • platform/merchant permission visibility;
  • secret leakage manual check;
  • load test result review.

12. Acceptance Criteria ​

Release / Merchant Transition считается согласованным для MVP, если:

  • Первый merchant переводится постепенно.
  • Payment methods переводятся по одному.
  • PO принимает решение о readiness.
  • MVP принимает Product Owner.
  • PO deployment approval перед каждым production deploy не обязателен.
  • Merchant сам начинает использовать v2 endpoints.
  • Merchant получает конкретные сроки перехода.
  • Formal sign-off не нужен.
  • Отдельный standalone checklist для первого merchant не нужен.
  • Перед live traffic выполняются minimum checks as part of release tasks / UAT scenarios.
  • Test transaction выполняется перед live traffic.
  • Date/time switch marker не хранится.
  • Migrated-to-v2 marker в Back Office не нужен.
  • Старая система продолжает работать, пока merchant использует v1.
  • Historical migration выполняется после прекращения v1 traffic по method.
  • Rollback system не нужна.
  • MVP acceptance основан на successful live deposit, webhook delivery, Back Office visibility and understandable timeline/routing.
  • MVP acceptance требует обязательные UAT/demo scenarios.
  • Load test обязателен для MVP acceptance.