08.04 Canonical Attributes Dictionary

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

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

Этот документ описывает canonical attributes для MVP.

Canonical attributes нужны, чтобы:

• merchant передавал данные в одном формате;
• hosted payment form дособирала данные в одном формате;
• provider adapters мапили наши поля в provider-specific field names;
• разные providers не навязывали системе свои названия fields;
• transaction context был consistent.

2. Naming style

Canonical attributes используют dot notation.

Примеры:

customer.email
customer.ip
redirectUrls.success

Provider-specific names не должны использоваться в public Merchant API.

Provider adapter должен мапить canonical name в provider field name на уровне кода.

Пример:

customer.ip -> ip
customer.ip -> ipAddress
customer.postalCode -> zip

3. Required customer fields in deposit request

Deposit request должен содержать:

• customer.email;
• customer.country;
• customer.firstName;
• customer.lastName.

Если эти fields не переданы:

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

4. Dynamic customer attributes

Hosted payment form может дособирать customer attributes, если выбранный provider method / SUB MID требует дополнительные данные.

Dynamic customer attributes описываются в коде provider adapter.

Если provider method требует дополнительное поле, которого нет в transaction customer context, hosted form собирает его в canonical format.

Dynamic attributes MVP:

• customer.ip;
• customer.address;
• customer.city;
• customer.phone;
• customer.postalCode;
• customer.dateOfBirth.

Также provider method может потребовать уже известные fields:

• customer.email;
• customer.country;
• customer.firstName;
• customer.lastName.

Если эти fields уже были переданы merchant-ом, hosted form может показать их как prefilled/read-only values.

Если required deposit DTO field не был передан merchant-ом, transaction не создается и hosted form не открывается.

5. Customer attributes dictionary

Attribute	Source	Required in deposit request	Can be collected on hosted form	Notes
customer.email	Merchant request	Yes	No	Required for transaction creation. Can be shown prefilled/read-only.
customer.country	Merchant request	Yes	No	Required for transaction creation. Can be shown prefilled/read-only.
customer.firstName	Merchant request	Yes	No	Required for transaction creation. Can be shown prefilled/read-only.
customer.lastName	Merchant request	Yes	No	Required for transaction creation. Can be shown prefilled/read-only.
customer.ip	Hosted form / provider requirement	No	Yes	Used when provider method requires customer IP.
customer.address	Hosted form / provider requirement	No	Yes	Customer address.
customer.city	Hosted form / provider requirement	No	Yes	Customer city.
customer.phone	Hosted form / provider requirement	No	Yes	Customer phone number.
customer.postalCode	Hosted form / provider requirement	No	Yes	Postal/ZIP code.
customer.dateOfBirth	Hosted form / provider requirement	No	Yes	Date of birth.

Note:

Required in deposit request means transaction cannot be created without the field.

Can be collected on hosted form means field may be requested after transaction creation if provider method requires it.

6. Payment/request fields

Deposit request payment fields:

• amount;
• currency;
• paymentMethodId;
• brandId;
• transactionId;
• userId;
• webhookUrls;
• redirectUrls.success;
• redirectUrls.pending;
• redirectUrls.cancel;
• redirectUrls.fail.

7. Payment/request attributes dictionary

Attribute	Required	Notes
amount	Yes	Original amount from merchant request.
currency	Yes	Original currency from merchant request.
paymentMethodId	Yes	UUID of merchant-level Payment Method / MID configuration.
brandId	Yes	Brand context for transaction and hosted payment form.
transactionId	Yes	Merchant transaction ID, unique within merchant.
userId	Yes	Merchant-side customer/user identifier.
webhookUrls	Yes	List of webhook URLs for transaction callbacks.
redirectUrls.success	Yes	Success redirect URL.
redirectUrls.pending	Yes	Pending redirect URL.
redirectUrls.cancel	Yes	Cancel redirect URL.
redirectUrls.fail	Yes	Fail redirect URL.

8. Technical request attributes

Technical request attributes are not part of MVP canonical attributes.

Not included in MVP:

• request.ip;
• request.userAgent;
• request.locale.

If these values are needed technically, development team can capture them internally, but they are not product-level canonical attributes for Merchant API / hosted form MVP.

9. Card data

Card data is not part of gateway canonical attributes in MVP.

Card data fields are out of scope for this gateway.

Reason:

• card processing uses separate service;
• card data should not be stored/handled by this gateway;
• PCI/security scope should remain outside this product area.

Examples not included:

• card number;
• card holder name;
• expiration date;
• CVV;
• card token.

10. Provider adapter mapping

Provider adapter maps canonical attributes to provider-specific fields in code.

Example:

customer.ip -> ipAddress
customer.postalCode -> zip
customer.dateOfBirth -> dob

Mapping is not configured through Back Office in MVP.

Provider method adapter must define:

• provider-specific required customer attributes;
• optional customer attributes;
• provider field mapping;
• validation/formatting rules, if needed;
• which fields can be collected on hosted payment form;
• hosted form input type;
• English label;
• future localization key.

11. Hosted form behavior

If provider method requires additional attributes:

1. System detects missing canonical attributes.
2. Hosted form shows missing fields.
3. Fields already received from merchant are prefilled and read-only.
4. Customer fills missing fields.
5. Hosted form submits canonical attributes back to system.
6. System saves submitted attributes in transaction customer context.
7. Provider adapter maps canonical attributes to provider fields.

Customer should not see provider-specific field names.

12. Attribute visibility

Customer attributes can be visible in transaction details according to permissions and privacy rules.

Provider-specific field mapping should be visible only to platform/internal users if needed for investigation.

Merchant users should see canonical fields, not provider-specific fields.

13. Acceptance Criteria

Canonical Attributes Dictionary считается согласованным для MVP, если:

• Attribute naming uses dot notation.
• Required customer fields: customer.email, customer.country, customer.firstName, customer.lastName.
• Dynamic hosted form attributes include customer.ip, customer.address, customer.city, customer.phone, customer.postalCode, customer.dateOfBirth.
• Payment/request fields include amount, currency, paymentMethodId, brandId, transactionId, userId, webhookUrls, redirectUrls.success/pending/cancel/fail.
• Technical request attributes request.ip/request.userAgent/request.locale are not product-level MVP canonical attributes.
• Card data is out of gateway scope and not included in canonical attributes.
• Provider adapter maps canonical names to provider-specific fields in code.
• Provider-specific field names are not exposed to merchant/customer.
• Hosted form collects missing canonical attributes, not provider-specific attributes.
• Hosted form saves customer-entered missing attributes in transaction customer context.
• Hosted form field labels are English-only in MVP.
• Provider adapter schema must include future localization key.

14. Open Questions

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

Technical/design follow-up:

1. Определить exact validation formats for each canonical attribute.
2. Определить UI labels for hosted form fields.
3. Определить storage/privacy rules для customer attributes.
4. Определить provider adapter mapping format in code.
5. Определить localization requirements for hosted form field labels.