11.01 Transaction Data Requirements

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

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

Этот документ описывает product-level data requirements для transaction.

Это не database schema.

Product Owner не определяет:

• table names;
• column names;
• indexes;
• foreign keys;
• partitioning;
• migrations;
• storage engine details.

Development team должна спроектировать database schema на основе этих product requirements.

2. Основной принцип

Transaction должна хранить весь business context, который нужен для:

• processing;
• status lifecycle;
• routing investigation;
• support investigation;
• merchant webhook payload;
• Back Office transaction details;
• transaction export;
• auditability;
• migration/historical visibility.

Правило:

Все данные, которые merchant/customer передал в transaction flow, должны быть сохранены, если они не являются secret values.

Secret values не должны сохраняться в transaction data.

3. Merchant/request data

Transaction должна сохранять все данные, которые merchant передал при create deposit request.

Минимально это включает:

• merchant identifier;
• brand identifier;
• paymentMethodId;
• merchant transactionId;
• merchant userId;
• webhookUrls;
• redirectUrls;
• amount;
• currency;
• customer data;
• any optional merchant metadata/attributes, если они поддерживаются request schema;
• raw/canonical request context, если development team решит, что это нужно для investigation.

Важно:

• merchant request data нужна для support/investigation;
• merchant webhook payload строится на основе transaction data;
• duplicate merchant transactionId validation должна быть возможна;
• search/filter/export должны иметь доступ к agreed transaction fields.

4. Customer data

Transaction должна сохранять customer data, переданные merchant-ом или customer-ом.

Минимальный customer context:

• email;
• country;
• firstName;
• lastName;
• ip;
• address;
• city.

Если hosted payment form дособрала дополнительные customer attributes, они также должны быть сохранены in transaction customer context.

Примеры:

• provider-specific customer attribute;
• normalized canonical attribute;
• value submitted by customer on hosted form;
• timestamp of submission, если нужно для investigation.

Customer data naming должна быть canonical внутри нашей системы.

Provider-specific field names не должны становиться public/internal canonical naming.

5. Amount and FX snapshot

Transaction должна всегда хранить:

• original amount;
• original currency;
• amount in EUR;
• conversion date/time;
• conversion rate used.

EUR является base currency for internal calculations.

FX snapshot нужен для:

• velocity limits;
• fee calculation;
• reporting/export;
• support investigation;
• deterministic historical view.

Если позже rate изменился, historical transaction не должна пересчитываться без explicit correction/recalculation logic.

6. Provider references

Transaction должна сохранять provider references, если provider их вернул.

Нужно хранить:

• providerTransactionId;
• accountReference, если provider вернул IBAN/account/reference/other account identifier.

providerTransactionId и accountReference могут использоваться:

• в merchant webhook payload;
• в Back Office transaction details;
• в transaction search/filter/export;
• для support investigation.

Provider reference не должен раскрывать hidden provider identity/configuration merchant user-у сверх agreed visibility rules.

7. Manual correction marker

Transaction должна хранить marker:

corrected = true/false

Если была manual correction:

• transaction details должны показывать, что status был corrected;
• merchant webhook payload должен содержать corrected;
• timeline должен показывать correction event;
• audit log должен показывать user action.

8. Legacy marker

Transaction должна хранить marker:

legacy = true/false

legacy = true означает, что transaction migrated from old system.

Legacy transaction behavior:

• read-only;
• no webhook sending;
• no provider actions;
• no manual correction;
• visible legacy marker in list/details/export.

8.1 Test marker

Transaction должна хранить marker:

test = true/false

test = true означает, что transaction создана через sandbox/test provider flow.

Test transaction behavior:

• visible in normal transaction list;
• visible in transaction details;
• visible test marker/badge in list/details;
• sends merchant webhooks;
• can participate in velocity limits / fees / turnover in test context;
• available for filtering/search/export if user has access to field.

Test marker нужен, чтобы users clearly distinguish sandbox/test traffic from real production traffic.

9. Legacy migration identifiers

Migration должна быть реализована без раздувания основной transaction model лишними legacy fields.

Product requirement:

• migrated transaction must be searchable/investigable by old identifiers where needed;
• migration report must be able to show mapping from old transaction to new transaction;
• old identifiers should be stored in a structured migration/legacy metadata area, not as many first-class fields on all transactions.

Examples of legacy identifiers that may be needed:

• old transaction ID;
• old merchant ID;
• old merchantConfigId;
• old provider transaction ID, if available.

Development team должна предложить exact storage approach.

Product preference:

• keep normal transaction model clean;
• keep legacy data grouped;
• do not create many nullable legacy columns on every transaction unless development team has strong reason.

10. Routing result summary

Transaction summary/details должна хранить final routing result.

Нужно сохранять:

• selected payment method configuration;
• matched first-level rule / ruleSet reference;
• selected MASTER MID GROUP;
• selected MASTER MID;
• matched MASTER MID routing rule / ruleSet reference;
• selected SUB MID GROUP;
• selected SUB MID or SUB MID AGGREGATOR;
• provider reference/name for platform visibility;
• fallback attempts summary;
• skipped/rejected candidate summary.

Routing result нужен для:

• investigation;
• support;
• merchant-safe visibility;
• platform full visibility;
• timeline;
• export, если fields доступны user-у.

Exact normalized storage is development team responsibility.

11. Routing visibility

Merchant user должен видеть routing summary only in safe/filtered form.

Merchant-safe routing visibility:

• payment method;
• first-level routing result;
• MASTER MID GROUP;
• MASTER MID;
• high-level status/reason;
• merchant-created SUB MID/SUB MID GROUP only if user has access and permission.

Merchant user не должен видеть:

• platform-created hidden SUB MID internals;
• SUB MID AGGREGATOR internals;
• hidden provider details;
• provider credentials/config;
• internal provider failure details.

Platform user with permission должен видеть full routing result.

12. Transaction data for list/search/export

Transaction data must support Back Office list/search/export requirements.

Transaction list/export fields include:

• merchant name;
• brand name;
• transaction ID;
• merchant transaction ID;
• merchant user ID;
• merchant group;
• user email;
• MID ID;
• MID name;
• type;
• amount original;
• amount in EUR;
• currency;
• status;
• account reference;
• created;
• updated;
• legacy marker;
• test marker;
• corrected marker.

Exact list column implementation is UI/technical decision.

Product requirement:

• fields visible in UI/export must be backed by transaction data or related readable entities;
• export by current filters must include only fields available to current user by permissions/visibility.

13. Data ownership

Transaction data should be owned by Orchestrator Service.

Gateways can create request/session records or publish events, but final transaction business state belongs to Orchestrator Service.

Development team decides exact boundary:

• whether Merchant Gateway creates transaction record directly;
• whether Orchestrator creates transaction record from DepositRequested;
• whether minimal request/session record is separate from transaction record.

Product requirement:

• accepted request must be durably stored or queued;
• transaction state must be consistent;
• hosted form must be able to poll session/transaction state;
• transaction data must be available for Back Office, webhooks, exports and investigation.

14. Secrets and sensitive data

Secret values must not be stored in transaction data.

Examples:

• API key secret;
• provider credentials;
• provider secret keys;
• webhook signing secret;
• session token raw secret, if token is sensitive and can be stored only hashed;
• passwords;
• 2FA secrets.

Sensitive non-secret data, such as customer email/IP/address, can be stored if required for transaction processing/investigation, but visibility/export must respect permissions.

14.1 Environment

Transaction data не должна хранить environment как product field.

Transaction details не должны показывать environment.

Reason:

• transaction already belongs to one deployed environment;
• environment is runtime/deployment context, not business transaction context;
• environment field does not help normal merchant/support investigation.

15. Acceptance Criteria

Transaction Data Requirements считаются согласованными для MVP, если:

• Transaction stores all merchant/customer-provided non-secret data.
• Customer data includes email, country, firstName, lastName, ip, address, city.
• Hosted form collected attributes are saved in transaction customer context.
• Transaction stores original amount/currency.
• Transaction stores amount in EUR.
• Transaction stores conversion date/time and conversion rate.
• Transaction stores providerTransactionId if provider returns it.
• Transaction stores accountReference if provider returns it.
• Transaction stores corrected marker.
• Transaction stores legacy marker.
• Transaction stores test marker.
• Migration legacy identifiers are stored without bloating normal transaction model with many first-class legacy fields.
• Transaction stores final routing result summary.
• Merchant user sees routing summary only in safe/filtered form.
• Platform user with permission sees full routing result.
• Transaction data supports list/search/export requirements.
• Orchestrator Service owns final transaction business state.
• Secrets are not stored in transaction data.
• Environment is not stored as transaction product field.
• Transaction details do not show environment.

16. Open Questions

Product open questions отсутствуют.

Technical/design follow-up:

1. Development team должна предложить exact database schema.
2. Development team должна предложить exact storage for full merchant/customer request context.
3. Development team должна предложить exact storage for hosted form collected attributes.
4. Development team должна предложить exact legacy metadata storage approach.
5. Development team должна предложить exact routing result snapshot structure.
6. Development team должна определить indexes for search/filter/export.
7. Development team должна определить retention/security rules for sensitive customer data.