Payment Orchestrator

Тема

05.06 Provider / SUB MID Integration Contract ​

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

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

Этот документ описывает product requirements к provider integrations, SUB MID и SUB MID AGGREGATOR.

Документ покрывает:

  • как provider integrations называются и скрываются;
  • provider methods;
  • required/optional attributes;
  • canonical attribute naming;
  • SUB MID configuration;
  • SUB MID AGGREGATOR;
  • callback URL hiding;
  • provider adapter responsibilities;
  • raw provider data storage.

2. Provider names ​

В коде provider integrations могут называться реальными provider names.

Список providers хранится в коде.

Provider появляется в UI только если он реализован на уровне provider adapter / integration code.

Но реальные provider names не должны случайно попадать наружу:

  • в public API docs;
  • в merchant-facing UI;
  • в hosted payment form;
  • в merchant webhook payload;
  • в customer-facing errors;
  • в callback URLs;
  • в swagger/openapi, если он доступен наружу.

Merchant может увидеть provider name только если ему явно выдан provider access и у него есть соответствующие permissions.

Platform users с нужными permissions могут видеть реальные provider names.

Merchant users без Provider Access не должны видеть реальные provider names вообще.

Merchant users с Provider Access и permissions могут видеть реальное provider name.

3. Provider methods ​

Provider может предоставлять несколько payment methods.

Примеры:

  • cards;
  • apple pay;
  • google pay;
  • sofort;
  • blik;
  • crypto;
  • APM method;
  • other provider-specific methods.

Список provider methods хранится в коде.

Provider method появляется в UI только если:

  • method реализован на уровне provider adapter;
  • method доступен для создания SUB MID;
  • user имеет право видеть provider/method в текущем context.

Если provider теоретически поддерживает method, но этот method не реализован в нашем коде, method не должен показываться в Back Office.

Для каждого provider method в коде должен быть описан список:

  • provider-specific required customer attributes;
  • optional customer attributes;
  • secret/method-specific config fields, если нужны;
  • non-secret config fields, если нужны;
  • validation rules;
  • hosted form input metadata.

Merchant user не должен заранее видеть список required attributes provider method до создания SUB MID.

Provider method status в Back Office в MVP не нужен. Временная недоступность provider method считается operational agreement / operational handling, а не отдельной product setting.

4. Canonical attribute naming ​

Все customer/payment attributes в нашей системе должны иметь canonical naming.

Provider adapters должны мапить canonical attributes в provider-specific field names.

Пример:

text
Canonical attribute: customer.ip
Provider A field: ip
Provider B field: ipAddress

Merchant должен передавать данные в одном consistent формате, независимо от provider-specific naming.

Hosted payment form тоже должна собирать missing attributes в canonical format.

5. Deposit DTO fields and provider attributes ​

Обязательные fields для создания deposit описываются на уровне Merchant Deposit API DTO.

Если merchant не передал mandatory merchant-level fields для deposit request, transaction не создается.

Provider adapter schema не должна дублировать deposit DTO required fields как отдельную merchant-required модель.

Provider adapter schema отвечает за provider-specific requirements, которые появляются после routing и выбора SUB MID / provider method.

Для каждого provider method нужно знать:

  • какие дополнительные customer attributes обязательны для provider execution;
  • какие customer attributes optional;
  • какие attributes можно дособрать на hosted payment form;
  • какие config fields нужны для SUB MID / SUB MID AGGREGATOR;
  • какие config fields являются secret/internal settings и не относятся к customer input.

Если transaction создана, но выбранному SUB MID / SUB MID GROUP нужны дополнительные customer attributes, hosted payment form должна дособрать missing customer attributes.

Customer-entered missing fields должны сохраняться в transaction customer context.

Provider adapter должен описывать hosted form metadata:

  • canonical attribute name;
  • input type;
  • validation rules;
  • English label;
  • future localization key.

Labels hosted form в MVP только на английском.

Код должен быть заложен так, чтобы в будущем добавить мультиязычность.

6. SUB MID ​

SUB MID является provider method configuration.

При создании SUB MID в Back Office user выбирает:

  • provider;
  • provider method.

Пример:

text
Provider: Interkassa
Provider method: Cards
SUB MID: Interkassa Cards Config #1

Если SUB MID создан под Cards, он может быть добавлен в routing под card-related MASTER MID / payment method configuration.

SUB MID не должен использоваться в routing для несовместимого payment method.

provider и provider method нельзя изменить после создания SUB MID.

Если требуется другой provider или provider method, нужно создать новую configuration.

7. SUB MID configuration ​

SUB MID содержит configuration для provider method execution.

Обычно credentials/config одинаковые для provider configuration в целом, но система должна поддерживать method-specific additional fields.

SUB MID configuration может включать:

  • provider credentials;
  • merchant/provider account identifiers;
  • API endpoints/modes;
  • method-specific secret fields;
  • method-specific settings;
  • email replacement setting;
  • status;
  • expiration time;
  • velocity limits;
  • FX / conversion fee;
  • callback validation settings, если применимо.

Provider adapter должен описывать config schema для SUB MID / SUB MID AGGREGATOR.

Config fields могут быть:

  • secret required;
  • secret optional;
  • non-secret required;
  • non-secret optional;
  • boolean;
  • enum/select;
  • string/text;
  • number;
  • URL;
  • mode/environment selector, если нужно.

Secret configuration fields доступны в UI только для ввода нового значения.

После сохранения secret values шифруются и больше никогда не раскрываются.

Non-secret config fields доступны в UI users с permission и entity visibility access.

Audit logs, exports и system logs не должны хранить old/new secret values ни в открытом, ни в masked, ни в encrypted виде.

Credentials/config должны иметь version/history.

Historical transaction должна ссылаться на credentials/config version, которая использовалась во время provider execution.

Historical transaction не должна раскрывать secret values.

Rollback credentials/config к старой version в MVP не нужен.

OTP / 2FA confirmation для изменения SUB MID / SUB MID AGGREGATOR credentials/config в MVP не нужен.

8. Method-specific secret fields ​

Некоторые provider methods могут требовать дополнительные secret fields или настройки.

Система должна позволять описывать такие fields на уровне provider method adapter/config schema.

Примеры:

  • additional secret key for Apple Pay;
  • method-specific terminal ID;
  • method-specific callback secret;
  • method-specific certificate reference;
  • method-specific mode flag.

Эти fields не должны быть видны merchant users без explicit provider access and permission.

Если user имеет permission и visibility access, secret fields показываются как обычные inputs только для ввода нового значения.

9. SUB MID AGGREGATOR ​

SUB MID AGGREGATOR является reusable provider configuration.

SUB MID AGGREGATOR может использоваться разными merchants.

Product-level model:

text
SUB MID: aggregator = false
SUB MID AGGREGATOR: aggregator = true

SUB MID и SUB MID AGGREGATOR имеют одинаковую provider execution модель.

Required fields такие же, как у SUB MID:

  • name;
  • provider;
  • provider method;
  • method;
  • status;
  • credentials/config;
  • createdByType.

provider и provider method нельзя изменить после создания SUB MID AGGREGATOR.

SUB MID AGGREGATOR поддерживает те же configurable settings, что SUB MID:

  • method-specific secret/settings fields;
  • expiration time;
  • email replacement / fake email generation;
  • velocity limits;
  • FX / conversion fee;
  • callback validation settings, если применимо.

Processing fee не настраивается на SUB MID AGGREGATOR.

Processing fee находится только на MASTER MID.

SUB MID AGGREGATOR доступен только platform users.

Merchant users не могут:

  • создавать SUB MID AGGREGATOR;
  • редактировать SUB MID AGGREGATOR;
  • видеть credentials/config SUB MID AGGREGATOR;
  • видеть internal provider details SUB MID AGGREGATOR, если это platform-hidden configuration.

SUB MID AGGREGATOR может быть использован в routing как candidate внутри SUB MID GROUP.

Если SUB MID AGGREGATOR inactive, routing должен пропустить его через fallback.

Если SUB MID или SUB MID AGGREGATOR soft-deleted, routing должен пропустить candidate через fallback, а historical transactions должны продолжать показывать execution snapshot, который был использован на момент transaction execution.

10. Callback URL hiding ​

Provider callback URL должен быть opaque / non-provider-revealing.

Callback URL не должен содержать real provider name.

Цель:

  • если public docs/swagger случайно будут exposed, provider names не должны раскрыться;
  • merchant/customer не должны узнать real provider names по callback URL;
  • provider-sensitive implementation details не должны быть видны наружу.

Exact strategy может быть предложена development team:

  • hash;
  • opaque route ID;
  • callback token;
  • integration ID;
  • другой безопасный approach.

Product requirement: real provider name не должен быть частью public callback URL.

11. Provider adapter responsibilities ​

Provider adapter должен уметь:

  • create payment;
  • validate callback;
  • map callback status;
  • map provider error;
  • build hosted/iframe redirect behavior;
  • map canonical attributes to provider fields;
  • map provider response to internal transaction data;
  • expose provider method required/optional attributes to internal system;
  • support callback validation rules;
  • return unified internal errors.

11.1 Test provider / sandbox adapter ​

В MVP должен быть test provider adapter.

Test provider adapter должен:

  • support all MVP payment methods;
  • return hosted redirect URL;
  • simulate PROCESSING;
  • simulate COMPLETED;
  • simulate FAILED;
  • simulate CANCELED;
  • simulate REJECTED;
  • simulate provider timeout;
  • simulate provider error response;
  • allow merchant/admin to intentionally choose/simulate expected test outcome.

Test provider должен проходить через normal execution flow:

  • routing;
  • SUB MID / SUB MID AGGREGATOR configuration;
  • hosted payment form / redirect;
  • provider callback;
  • status mapping;
  • merchant webhook;
  • transaction timeline.

Dedicated test provider controls для duplicate callback / ignored callback / amount-currency mismatch / invalid callback signature в MVP не обязательны.

Эти scenarios должны покрываться automated/integration tests.

12. Provider polling ​

Provider polling status в MVP не нужен.

MVP работает через provider callbacks.

Если provider не присылает callback, transaction должна обрабатываться по expiration rules.

Polling может быть добавлен позже для specific providers, если будет отдельное requirement.

13. Raw provider request / response ​

Система должна хранить raw provider request / response по каждому provider interaction.

Это нужно для:

  • investigation;
  • support;
  • provider dispute;
  • error mapping;
  • callback validation;
  • debugging integrations.

Raw provider data видят только platform users с соответствующей permission.

Merchant users не должны видеть raw provider request/response, если это раскрывает provider/internal details.

Secret fields внутри raw data не должны сохраняться как значения. Non-secret sensitive fields могут быть masked, если это возможно без потери investigation value.

14. Timeline ​

Transaction timeline должна фиксировать provider integration events:

  • provider adapter selected;
  • required attributes checked;
  • missing attributes detected;
  • SUB MID configuration loaded;
  • provider request built;
  • provider request sent;
  • provider response received;
  • provider payment URL received;
  • callback received;
  • callback validation completed;
  • provider error mapped;
  • raw provider data saved.

Merchant-safe timeline должна скрывать provider-sensitive details.

Platform timeline должна показывать full provider integration trace.

15. Audit log ​

Изменения SUB MID / SUB MID AGGREGATOR configuration должны попадать в audit log.

Audit log должен фиксировать:

  • provider selected;
  • provider method selected;
  • config created;
  • config updated;
  • config status changed;
  • credentials/config updated;
  • method-specific settings updated;
  • velocity/FX/expiration changes;
  • actor;
  • timestamp.

16. Acceptance Criteria ​

Provider / SUB MID Integration Contract считается согласованным для MVP, если:

  • Provider names могут быть реальными в коде.
  • Provider names не раскрываются в public/merchant/customer-facing surfaces без explicit permission.
  • Provider может иметь несколько methods.
  • Deposit DTO required fields описываются на уровне Merchant Deposit API.
  • Provider adapter schema не дублирует deposit DTO required fields.
  • Для каждого provider method в коде описаны provider-specific required customer attributes.
  • Для каждого provider method в коде описаны optional customer attributes.
  • Для каждого provider method в коде описаны hosted form input metadata.
  • Hosted form input metadata содержит input type, validation rules, English label and future i18n key.
  • Labels hosted form в MVP только на английском.
  • Customer-entered missing fields сохраняются в transaction customer context.
  • Provider adapter schema описывает SUB MID / SUB MID AGGREGATOR config fields.
  • SUB MID config fields поддерживают secret/non-secret, required/optional and boolean fields.
  • Attributes используют canonical naming в нашей системе.
  • Provider adapter мапит canonical attributes в provider-specific fields.
  • SUB MID создается как provider + provider method configuration.
  • SUB MID required fields: name, provider, provider method, method, status, credentials/config, createdByType.
  • SUB MID provider нельзя менять после создания.
  • SUB MID provider method нельзя менять после создания.
  • SUB MID нельзя использовать для несовместимого payment method.
  • SUB MID поддерживает common config и method-specific secret/settings fields.
  • Secret values SUB MID / SUB MID AGGREGATOR шифруются и не раскрываются после сохранения.
  • Secret можно только заменить новым введенным значением.
  • Non-secret config fields можно повторно открыть после сохранения, если user имеет permission и visibility access.
  • SUB MID / SUB MID AGGREGATOR credentials/config имеют version/history.
  • Historical transaction ссылается на credentials/config version used.
  • Historical transaction не раскрывает secret values.
  • Rollback credentials/config к старой version в MVP не нужен.
  • OTP / 2FA confirmation для изменения credentials/config не нужен.
  • Audit log не хранит old/new secret values.
  • SUB MID AGGREGATOR является reusable platform-only configuration.
  • SUB MID AGGREGATOR required fields: name, provider, provider method, method, status, credentials/config, createdByType.
  • SUB MID AGGREGATOR provider нельзя менять после создания.
  • SUB MID AGGREGATOR provider method нельзя менять после создания.
  • Merchant users не могут создавать/редактировать SUB MID AGGREGATOR.
  • SUB MID и SUB MID AGGREGATOR можно soft-delete даже если по ним есть transactions.
  • Historical transactions сохраняют execution snapshot SUB MID / SUB MID AGGREGATOR.
  • Callback URL не раскрывает real provider name.
  • Provider adapter умеет create payment, validate callback, map callback status, map provider error, build hosted/iframe redirect.
  • Test provider adapter существует в MVP.
  • Test provider adapter поддерживает все MVP payment methods.
  • Test provider adapter возвращает hosted redirect URL.
  • Test provider adapter может симулировать PROCESSING, COMPLETED, FAILED, CANCELED, REJECTED.
  • Test provider adapter может симулировать provider timeout and provider error response.
  • Test provider adapter позволяет intentionally choose/simulate expected test outcome.
  • Duplicate/ignored/mismatch/invalid-signature callback scenarios покрываются tests and не требуют dedicated test provider controls.
  • Provider polling не входит в MVP.
  • Raw provider request/response сохраняются.
  • Raw provider data доступны только platform users с permission.
  • Provider integration events пишутся в timeline.
  • SUB MID / SUB MID AGGREGATOR changes пишутся в audit log.

17. Open Questions ​

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

Technical/design follow-up:

  1. Определить exact provider adapter interface.
  2. Определить provider method config schema format.
  3. Определить canonical attribute dictionary.
  4. Определить callback URL hiding strategy.
  5. Определить raw provider data masking rules.
  6. Определить compatibility validation between SUB MID method and payment method routing.