Payment Orchestrator

Тема

12.01 Merchant Public Documentation Requirements ​

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

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

Этот документ описывает требования к merchant-facing документации для MVP.

Merchant documentation нужна, чтобы merchant мог самостоятельно интегрироваться с новой системой:

  • создать deposit через /api/v2/deposit;
  • подписать request;
  • обработать response;
  • открыть hosted payment URL для customer;
  • принимать merchant webhooks;
  • валидировать webhook signature;
  • понимать transaction statuses;
  • понимать merchant-facing error codes;
  • протестировать sandbox/test flow.

2. Формат документации ​

Документация для merchant должна быть опубликована в публичном портале.

Back Office может ссылаться на documentation portal, но сама документация не должна существовать только внутри Back Office.

Product requirement:

text
Merchant documentation is delivered through a public documentation portal.

3. Documentation owner ​

Owner merchant documentation:

text
Product Owner

Development/security team должны предоставить technical details:

  • exact HMAC signing format;
  • exact headers;
  • request canonicalization rules;
  • webhook signature validation rules;
  • code examples;
  • sandbox/test integration details.

Но product/content ownership остается за Product Owner.

4. Обязательный content scope ​

Merchant public documentation в MVP должна содержать:

  • overview новой Merchant API integration;
  • authentication / request signing;
  • POST /api/v2/deposit request;
  • create deposit success response;
  • create deposit error response;
  • required request fields;
  • webhookUrls rules;
  • redirectUrls rules;
  • hosted payment URL behavior;
  • payment session behavior на high level;
  • transaction statuses;
  • merchant-facing error codes;
  • merchant webhook payload schema;
  • merchant webhook event types;
  • merchant webhook signature validation;
  • webhook delivery success criteria;
  • webhook retry behavior;
  • sandbox/test provider flow.
  • environment base URLs.

Documentation должна разделять base URLs:

  • stg;
  • prod.

local and dev URLs не нужно публиковать merchant-ам.

Documentation должна объяснять:

  • sandbox/test flow работает в stg;
  • test provider также доступен in prod;
  • API keys are environment-specific;
  • merchant должен использовать key from the same environment as API base URL.

5. HMAC signing examples ​

Merchant documentation должна описывать HMAC request signing пошагово.

Документация должна включать examples на нескольких programming languages.

Минимально:

  • JavaScript / TypeScript;
  • PHP;
  • Python;
  • Java or C#.

Exact list of languages может быть уточнен Product Owner-ом совместно с merchant/support context.

Documentation должна объяснять:

  • какие headers нужно отправлять;
  • какие request fields входят в signature;
  • как формируется payload / canonical string;
  • как считается HMAC;
  • как передается signature;
  • как работает timestamp/replay protection, если используется;
  • как работает key rotation grace period.

Exact cryptographic format должна предложить development/security team.

6. Webhook signature validation examples ​

Merchant documentation должна описывать webhook signature validation.

Нужно показать:

  • какие webhook headers приходят;
  • какой payload подписан;
  • как merchant проверяет HMAC signature;
  • что делать, если signature invalid;
  • как учитывать timestamp/replay protection, если используется.

Нужны code examples для webhook validation.

Минимальный language set должен быть таким же, как для request signing examples.

7. Transaction statuses documentation ​

Документация должна содержать список merchant-facing transaction statuses.

Минимально:

  • CREATED;
  • WAITING_CUSTOMER_DATA;
  • PROCESSING;
  • COMPLETED;
  • FAILED;
  • CANCELED;
  • REJECTED.

Для каждого status нужно описать:

  • что status означает для merchant;
  • является ли status final;
  • отправляется ли webhook для этого status;
  • какие merchant action expectations.

Важно:

text
PROCESSING must be explained as meaningful provider-side processing state,
not simply "request was sent to provider".

8. Error codes documentation ​

Документация должна содержать merchant-facing error codes and descriptions.

Для каждого error code нужно описать:

  • code;
  • human-readable description;
  • where it can appear;
  • whether transaction was created or not, if applicable;
  • suggested merchant action, if applicable.

Provider raw errors не должны публиковаться merchant-у.

Documentation must use unified merchant-facing error dictionary.

9. Sandbox / test flow ​

Merchant documentation должна описывать sandbox/test provider flow для MVP.

Минимально:

  • как создать test deposit;
  • как выбрать/simulate expected test status;
  • какие credentials/API key использовать в test environment;
  • какие test payment method/paymentMethodId использовать;
  • какие statuses можно получить в test flow;
  • как работает hosted redirect URL test provider-а;
  • как проверить webhook delivery;
  • как проверить signature validation;
  • как проверить failed deposit scenario, если test provider это поддерживает.
  • где merchant видит test transaction marker.

Test provider в MVP должен поддерживать:

  • all MVP payment methods;
  • PROCESSING;
  • COMPLETED;
  • FAILED;
  • CANCELED;
  • REJECTED;
  • provider timeout;
  • provider error response;
  • hosted redirect URL.

Exact sandbox/test provider mechanics должна предложить development/QA team.

10. What is not required in MVP ​

В MVP не требуется:

  • Postman collection as mandatory deliverable;
  • OpenAPI spec as mandatory merchant-facing deliverable;
  • troubleshooting section;
  • full Back Office embedded documentation;
  • interactive API explorer;
  • merchant-facing SDK.

OpenAPI/Swagger может использоваться internally или later, но не является обязательным deliverable для merchant documentation MVP.

11. Acceptance Criteria ​

Merchant Public Documentation считается согласованной для MVP, если:

  • Documentation опубликована в public documentation portal.
  • Documentation owner: Product Owner.
  • Documentation описывает /api/v2/deposit.
  • Documentation описывает request signing.
  • Request signing содержит step-by-step HMAC explanation.
  • Request signing содержит examples на нескольких programming languages.
  • Documentation описывает webhook signature validation.
  • Webhook signature validation содержит examples на нескольких programming languages.
  • Documentation содержит список transaction statuses.
  • Documentation содержит merchant-facing explanation для каждого status.
  • Documentation содержит error codes and descriptions.
  • Documentation описывает sandbox/test provider flow.
  • Documentation показывает stg/prod base URLs.
  • Documentation объясняет environment-specific API keys.
  • Documentation объясняет, что sandbox/test flow работает внутри stg.
  • Documentation объясняет, что test provider доступен in prod.
  • Documentation описывает how to choose/simulate test status.
  • Documentation описывает hosted redirect URL behavior for test provider.
  • Documentation описывает test transaction marker.
  • Postman collection не обязательна в MVP.
  • OpenAPI spec не обязательна как merchant-facing deliverable в MVP.
  • Troubleshooting section не обязательна в MVP.

12. Open Questions ​

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

Technical/content follow-up:

  1. Development/security team должна предложить exact HMAC request signing format.
  2. Development/security team должна предложить exact webhook signature validation format.
  3. Product Owner должен выбрать final language set для examples.
  4. Development/QA team должна описать sandbox/test provider mechanics.
  5. Product Owner должен подготовить final public documentation content.