03.02 Hosted Payment Form

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

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

Этот документ описывает hosted payment form, которую customer открывает после создания deposit transaction.

Hosted form не является страницей, где customer должен вручную выбирать статусы или видеть техническую информацию. Это orchestration page, которая:

• открывается по payment session token;
• загружает transaction data;
• ожидает результат routing;
• определяет, выбран ли SUB MID;
• дособирает недостающие attributes, если они нужны выбранному SUB MID / provider method;
• получает provider redirect/payment URL;
• делает redirect customer на provider redirect/payment URL;
• продолжает polling transaction data и реагирует на изменения transaction state.

2. Actors

Customer

Открывает hosted payment form и завершает payment flow.

Hosted Payment Form

Наша customer-facing страница, которая управляет customer flow.

Provider

Provider / acquirer, который предоставляет payment URL или H2H requirements.

3. Entry Point

Hosted payment form открывается по URL, содержащему payment session token.

https://payment-page.example.com/session/{paymentSessionToken}

Payment session token должен скрывать настоящий transaction ID.

Настоящий transaction ID не должен быть виден в hosted payment URL.

Payment session token хранится только внутри hosted payment URL. Hosted form не показывает token customer-у как отдельное значение.

Payment session expiration:

30 minutes

Expiration time должно быть configurable через environment variables.

Если payment session expired:

• transaction/session считается expired;
• customer видит generic expiration/error message;
• customer не видит technical reason;
• hosted form не делает redirect на merchant URL;
• hosted form не показывает retry button.

4. Branding

Hosted form должна иметь brand context внутри системы.

Brand определяется по brandId, который merchant передал при создании deposit.

В MVP hosted form не должна отображать customer:

• brand name;
• brand domain;
• brand styling.

Brand context нужен, чтобы transaction была связана с правильным brand и чтобы в будущем на основе brand можно было делать customization hosted form.

Кастомизация стилей hosted form не входит в MVP.

5. Initial Page Behavior

Когда customer открывает hosted payment form:

1. Страница загружается.
2. Форма показывает loading state.
3. Hosted form начинает polling transaction data.
4. Routing может еще выполняться.
5. Как только routing завершился и выбран SUB MID, hosted form получает дальнейшие instructions.

Customer не должен видеть технические статусы transaction.

Вместо этого UI должен показывать только простые customer-facing states:

• loading;
• form with missing required fields;
• redirecting to payment page;
• generic error message.

6. Routing Result Behavior

После того как routing завершился и определился SUB MID, возможны несколько вариантов.

Provider URL Is Available

Если SUB MID / provider method вернул payment URL:

1. Hosted form получает provider payment URL.
2. Hosted form делает redirect customer на provider payment URL.
3. Provider дальше ведет customer по своему payment flow.

Для MVP default behavior:

provider URL received -> redirect customer to provider URL

Iframe не является основным сценарием MVP, потому что provider page может:

• делать внутренние redirects;
• открывать 3DS / bank / wallet pages;
• запрещать embedding через browser security headers;
• некорректно работать внутри merchant iframe или nested iframe.

Iframe можно рассматривать только как provider-specific optimization после отдельной технической проверки конкретного provider flow.

Additional Attributes Are Required

Если выбранному SUB MID / provider method недостаточно attributes, переданных merchant:

1. Hosted form отображает form.
2. В form показываются все relevant customer fields.
3. Данные, которые merchant уже передал, prefilled.
4. Prefilled данные нельзя редактировать.
5. Недостающие fields отображаются как inputs.
6. Customer заполняет недостающие fields.
7. Customer нажимает continue.
8. Система сохраняет введенные данные в transaction customer context.
9. Система отправляет transaction дальше в provider execution.

7. Dynamic Attributes Form

Когда transaction ожидает дополнительные fields, hosted form должна показать всю форму customer data, а не только отдельные недостающие inputs.

Правило:

• fields, которые merchant уже передал, отображаются prefilled и read-only;
• fields, которых не хватает, отображаются editable;
• после submit система продолжает provider execution.

Пример:

Merchant передал:

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

Provider method требует дополнительно:

• ip;
• address;
• city.

Hosted form показывает всю customer form:

• email read-only;
• country read-only;
• firstName read-only;
• lastName read-only;
• ip pulled from client automatically;
• address editable;
• city editable.

Dynamic fields и их metadata берутся из provider adapter schema в коде.

Для каждого dynamic field adapter должен описать:

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

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

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

Provider-specific field names customer не видит.

8. Provider Display Mode

В MVP provider flow должен открываться через redirect.

Основное правило:

redirect by default

Это решение снижает риск, что provider page сломается из-за iframe restrictions, redirects, 3DS, bank authorization или wallet authorization.

Если hosted form открыта внутри merchant iframe, provider redirect может потребовать выхода из iframe в top-level browsing context.

Техническая команда должна предложить безопасный механизм для такого случая, например:

• documented merchant integration requirement для iframe sandbox/allow attributes;
• top-level navigation из hosted form, если browser это разрешает;
• отдельный fallback behavior, если top-level navigation невозможна.

Product requirement:

• customer не должен видеть provider technical details;
• если redirect невозможен технически, hosted form делает redirect на merchant fail URL, если он доступен;
• событие должно быть записано в transaction timeline.

Iframe в будущем разрешен только для тех provider flows, где development team явно подтвердила, что flow корректно работает end-to-end.

iframe only if explicitly supported for this provider flow

9. Polling

Hosted form должна работать через polling transaction data.

Форма должна периодически запрашивать состояние transaction/payment session и на основании этого выполнять действия:

• продолжать loading;
• показать dynamic attributes form;
• выполнить redirect на provider URL;
• показать generic error message;
• остановить flow, если transaction expired/final.

Важно: redirect выполняется на основании provider/payment session instructions, например когда система получила provider payment URL.

Точный polling interval должен предложить development team.

10. Customer Status Visibility

Customer не должен видеть технические transaction statuses.

Например, customer не должен видеть:

• CREATED;
• WAITING_CUSTOMER_DATA;
• PROCESSING;
• REJECTED;
• internal routing statuses.

Вместо этого customer видит только UX states:

• loading;
• required data form;
• redirecting to payment page;
• generic error.

В MVP customer также не должен видеть:

• amount;
• currency;
• payment method name;
• provider name;
• SUB MID / routing details.

11. Cancel Behavior

Hosted form не должна иметь cancel button в MVP.

Если customer закрыл страницу и ничего не сделал, transaction остается в текущем non-final status до expiration.

После expiration transaction должна перейти в:

CANCELED

12. Redirect Behavior

Redirect URLs передаются merchant при создании transaction.

В нормальном provider flow эти URLs передаются provider, и provider выполняет redirect customer на нужный URL.

Hosted form не должна по умолчанию самостоятельно делать success/failure redirect, если provider управляет redirect flow.

Если ошибка произошла на нашей стороне до передачи customer в provider flow, hosted form должна сделать redirect customer на merchant redirectUrls.fail.

Redirect на merchant fail URL является product requirement for MVP.

Если technical redirect невозможен, hosted form должна показать generic error message with reference ID and record event in transaction timeline.

13. Error Behavior

Если произошла ошибка, hosted form может показать generic customer-facing message:

Something went wrong. Please contact support and provide reference ID: {referenceId}.

Reference ID для customer-facing error:

transaction ID

Try again button в MVP не нужен.

Если ошибка произошла до provider flow, preferred behavior is redirect to merchant redirectUrls.fail.

Generic error message используется, если redirect технически невозможен или session expired/final state не может быть продолжен.

Технические причины ошибки должны сохраняться в transaction timeline и быть видны platform/support пользователям с permissions.

Customer не должен видеть provider raw error.

Customer не должен видеть:

• provider error;
• internal error;
• routing reason;
• velocity reason;
• provider name;
• SUB MID / routing details.

Hosted form language for MVP:

English only

14. Reopening Hosted Form

Customer может повторно открыть hosted payment form, если transaction:

• еще не final;
• еще не expired.

Если transaction expired, hosted form должна показать expiration screen.

Если transaction final, hosted form должна показать generic final/error state или обработать это согласно UX, который будет описан отдельно.

15. Timeline Events

Hosted form не должна сохранять все технические UI events в transaction timeline.

Для MVP transaction timeline должна содержать business-significant events:

• hosted payment session opened;
• routing result available;
• missing dynamic attributes required;
• dynamic attributes submitted;
• provider payment URL received;
• provider redirect used;
• provider redirect failed / blocked, если такое произошло;
• transaction expired.

Не нужно сохранять избыточные технические UI events, если они не помогают support расследовать transaction.

16. Acceptance Criteria

Hosted payment form считается реализованной для MVP, если:

• Hosted form открывается по payment session token.
• Transaction ID скрыт из hosted form URL.
• Payment session token хранится только внутри hosted payment URL.
• Payment session expires after 30 minutes, configurable via env.
• Hosted form использует brand context внутри системы.
• Hosted form не отображает brand name/domain/styling в MVP.
• Страница показывает loading state, пока routing / transaction data загружается.
• Hosted form polling получает transaction data и дальнейшие instructions.
• Если provider URL доступен, hosted form делает top-level redirect customer на provider URL.
• Iframe не используется как default provider display mode в MVP.
• Even iframe-only provider flows should be evaluated by technical team; MVP preference is top-level redirect.
• Если SUB MID требует дополнительные attributes, hosted form показывает customer form.
• Prefilled merchant data отображается read-only.
• Missing fields отображаются editable.
• После submit missing fields transaction отправляется дальше в provider execution.
• Если во время заполнения missing fields выбранный SUB MID стал unavailable / velocity exceeded, система пробует fallback candidate.
• Customer не видит технические transaction statuses.
• Customer не видит amount/currency.
• Customer не видит payment method name.
• Customer не видит brand name.
• Customer не видит raw provider errors.
• Customer не видит provider/internal/routing reasons.
• Customer видит только English UI в MVP.
• Hosted form не имеет cancel button в MVP.
• Hosted form не имеет Try again button в MVP.
• Если customer ничего не сделал, transaction остается non-final до expiration.
• После expiration transaction становится CANCELED.
• Для expired session hosted form показывает generic expiration/error screen without redirect.
• Internal error before provider flow redirects customer to merchant redirectUrls.fail.
• Customer-facing error reference ID is transaction ID.
• Hosted form можно открыть повторно, пока transaction не final и не expired.