Payment Orchestrator

Тема

05.15 Provider Adapter Schema ​

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

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

Этот документ описывает, что provider adapter должен описывать в коде для каждого provider method.

Provider adapter schema нужна для:

  • integration code;
  • validation provider execution;
  • dynamic hosted payment form;
  • SUB MID / SUB MID AGGREGATOR configuration UI;
  • canonical attribute mapping;
  • provider request building.

2. Core rule ​

Все provider-specific rules описываются в коде provider adapter.

Причина: под каждый provider и provider method все равно пишется integration code, поэтому schema должна быть рядом с adapter logic.

Back Office в MVP не является местом, где product/platform user вручную описывает provider method schema.

3. Deposit DTO vs provider adapter schema ​

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

Если merchant не передал обязательные поля deposit DTO:

  • transaction не создается;
  • merchant получает validation error;
  • hosted payment form не создается.

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

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

4. Customer attributes schema ​

Provider method может требовать дополнительные customer attributes.

Если transaction уже создана, но выбранному provider method нужны дополнительные customer attributes, которых нет в transaction context:

  • transaction остается созданной;
  • hosted payment form показывает dynamic inputs;
  • customer вводит недостающие данные;
  • данные сохраняются в transaction customer context;
  • provider execution продолжается.

Customer attributes schema должна описывать:

  • canonical attribute name;
  • provider-specific field mapping;
  • whether attribute is required for this provider method;
  • whether attribute can be collected on hosted form;
  • input type;
  • validation rules;
  • English label;
  • localization key / future i18n key.

Пример:

text
canonicalName: customer.ip
providerFieldName: ipAddress
requiredForProvider: true
collectableOnHostedForm: true
inputType: text
label.en: IP address
i18nKey: customer.ip.label

Provider-specific field names не должны показываться merchant или customer.

5. Optional customer attributes ​

Provider adapter может описывать optional customer attributes.

Optional attributes:

  • merchant может передать заранее;
  • hosted form не обязана их собирать;
  • provider adapter может отправить их provider-у, если они есть;
  • отсутствие optional attribute не блокирует provider execution.

6. SUB MID config schema ​

Provider adapter должен описывать, какие config fields можно задать при создании 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, если нужно.

Эти fields используются Back Office UI для создания и редактирования SUB MID / SUB MID AGGREGATOR.

Secret values:

  • вводятся через UI;
  • шифруются после сохранения;
  • не раскрываются повторно;
  • могут быть только заменены новым значением.

Non-secret config fields:

  • показываются повторно;
  • редактируются user-ом с permission и visibility access.

7. Hosted form input schema ​

Для hosted form provider adapter должен предоставить достаточно metadata, чтобы UI мог отрисовать input.

Минимально:

  • canonical attribute name;
  • input type;
  • English label;
  • validation rules;
  • required flag;
  • read-only flag, если value уже есть в transaction context;
  • future localization key.

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

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

8. Canonical naming ​

Merchant всегда передает и hosted form всегда сохраняет canonical attribute names.

Пример:

text
customer.ip

Если один provider ждет ip, а другой ipAddress, это решает provider adapter mapping.

Merchant не должен менять payload под provider-specific field names.

9. Saving collected data ​

Если customer ввел missing fields на hosted form, система должна сохранить эти данные в transaction customer context.

После сохранения:

  • provider adapter использует canonical attributes для provider request;
  • transaction details может показывать canonical customer fields согласно permissions/privacy rules;
  • timeline фиксирует, что customer attributes were collected.

10. Test provider schema ​

Test provider должен использовать тот же provider adapter schema approach, что и real providers.

Test provider schema должна описывать:

  • supported MVP methods;
  • hosted redirect URL behavior;
  • test outcome control mechanism;
  • supported simulated statuses;
  • timeout simulation;
  • provider error simulation;
  • callback mapping;
  • optional test configuration fields, если нужны;
  • hosted form metadata, если test flow требует inputs.

Test provider не должен обходить canonical attribute naming, transaction timeline, webhook sending or routing execution.

11. Acceptance Criteria ​

Provider Adapter Schema считается согласованной для MVP, если:

  • Provider-specific schema описывается в коде provider adapter.
  • Deposit DTO required fields описываются на уровне Merchant Deposit API, а не provider adapter.
  • Если deposit DTO required fields отсутствуют, transaction не создается.
  • Если provider-specific customer attributes отсутствуют после routing, hosted form дособирает их.
  • Provider adapter schema использует canonical attribute names.
  • Provider adapter мапит canonical names в provider-specific field names.
  • Provider-specific field names не показываются merchant/customer.
  • Customer attributes schema поддерживает input type, validation rules, English label and future i18n key.
  • Hosted form labels в MVP только на английском.
  • Код должен поддерживать будущую мультиязычность.
  • SUB MID config schema описывает secret/non-secret, required/optional and boolean fields.
  • Secret config values шифруются и не раскрываются повторно.
  • Non-secret config fields показываются и редактируются через UI.
  • Customer-entered missing fields сохраняются в transaction customer context.
  • Test provider использует тот же provider adapter schema approach.
  • Test provider schema описывает supported methods/statuses and hosted redirect behavior.

12. Open Questions ​

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

Technical/design follow-up:

  1. Определить exact TypeScript/DTO format provider adapter schema.
  2. Определить shared input type dictionary for hosted form and Back Office.
  3. Определить validation rule format.
  4. Определить i18n key naming convention.