Payment Orchestrator

Тема

03.15 Manual Transaction Correction ​

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

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

Этот документ описывает ручную коррекцию transaction status в Back Office.

Manual correction нужна для операционных случаев, когда status transaction нужно исправить вручную: из-за ошибки provider callback, внутренней ошибки, support investigation или бизнес-решения.

2. Кто может делать correction ​

Manual correction может выполнить любой Back Office user, если у него есть permission:

text
can_correct_transaction_status

Доступ зависит от:

  • user permissions;
  • merchant access;
  • merchant group access;
  • transaction visibility;
  • platform/merchant context.

Manual correction не является platform-only action.

Merchant user может делать correction, если имеет permission and access to transaction.

3. Какие statuses можно менять ​

Manual correction может менять transaction status на любой допустимый transaction status:

  • CREATED;
  • WAITING_CUSTOMER_DATA;
  • PROCESSING;
  • COMPLETED;
  • FAILED;
  • CANCELED;
  • REJECTED.

Correction не ограничивается только final statuses.

Можно изменить:

  • non-final -> final;
  • final -> final;
  • final -> non-final;
  • non-final -> non-final.

Такое действие должно использоваться осторожно and only with permission.

4. Required reason ​

При manual correction user обязан указать reason/comment.

Reason должен сохраняться:

  • в transaction timeline;
  • в audit log;
  • в correction details.

Без reason/comment correction нельзя выполнить.

5. Webhook resend decision ​

После выбора нового status система должна всегда спросить user-а:

text
Resend webhook to merchant?

Если user выбирает resend:

  • webhook отправляется на все webhook URLs transaction;
  • payload содержит новый status;
  • payload содержит corrected: true;
  • delivery attempts сохраняются в webhook delivery history;
  • action сохраняется в transaction timeline;
  • action сохраняется в audit log.

Если user не выбирает resend:

  • status все равно меняется;
  • webhook не отправляется;
  • decision сохраняется в timeline and audit log.

6. Webhook payload ​

Если webhook отправляется после manual correction:

  • payload schema такая же, как обычный merchant webhook;
  • field corrected должен быть:
json
true

Если corrected status связан с error/rejection/cancellation, payload должен содержать:

  • errorCode;
  • description.

7. Turnover impact ​

Manual correction влияет на monthly MASTER MID turnover для processing fee thresholds.

Rules:

  • если status меняется на COMPLETED, transaction должна быть добавлена в monthly turnover MASTER MID;
  • если status меняется из COMPLETED в non-COMPLETED, transaction должна быть убрана из monthly turnover MASTER MID;
  • если correction меняет один non-COMPLETED status на другой non-COMPLETED, turnover не меняется;
  • если correction меняет COMPLETED на COMPLETED, turnover не меняется.

Turnover recalculation должен быть deterministic and auditable.

8. Hosted payment form behavior ​

Hosted payment form не должна специально реагировать на manual correction после final status.

Customer-facing UX не меняется из-за manual correction.

Если customer повторно откроет hosted form после correction, form должна работать по обычным правилам для текущего transaction status / expiration state.

9. Legacy migrated transactions ​

Manual correction запрещена для migrated legacy transactions, которые marked as read-only.

Если user пытается сделать correction legacy read-only transaction:

  • action blocked;
  • UI показывает access/action not allowed message;
  • transaction status не меняется.

10. Timeline requirements ​

Transaction timeline должна сохранять:

  • manual correction requested;
  • previous status;
  • new status;
  • reason/comment;
  • actor;
  • timestamp;
  • webhook resend selected yes/no;
  • webhook resend result, если resend был выбран;
  • turnover recalculation triggered, если status affects COMPLETED turnover.

Merchant-safe timeline должна показывать correction event, если user имеет permission видеть transaction correction.

Hidden provider/internal details не должны раскрыться через correction reason/details.

11. Audit log ​

Manual correction должна попадать в audit log.

Audit log должен сохранять:

  • actor;
  • transaction ID;
  • merchant context;
  • previous status;
  • new status;
  • reason/comment;
  • webhook resend selected yes/no;
  • timestamp.

Если correction влияет на turnover, audit/timeline должны позволять понять, почему turnover изменился.

12. Acceptance Criteria ​

Manual Transaction Correction считается согласованной для MVP, если:

  • Correction доступна user-ам с permission.
  • Correction не является platform-only action.
  • Correction может менять status на любой допустимый transaction status.
  • Correction может менять final status на любой final status.
  • Correction может менять final status на non-final status.
  • Reason/comment обязателен.
  • После correction система всегда спрашивает, нужно ли resend webhook.
  • Если resend выбран, webhook отправляется на все transaction webhook URLs.
  • Correction webhook payload содержит corrected: true.
  • Correction webhook payload всегда содержит errorCode and errorDescription.
  • Если ошибки нет, errorCode and errorDescription равны null.
  • Correction на COMPLETED добавляет transaction в monthly MASTER MID turnover.
  • Correction из COMPLETED в non-COMPLETED убирает transaction из monthly MASTER MID turnover.
  • Hosted payment form не имеет специального behavior для post-final correction.
  • Correction запрещена для migrated legacy read-only transactions.
  • Correction пишется в transaction timeline.
  • Correction пишется в audit log.