Payment Orchestrator

Тема

03.01 Merchant Creates Deposit ​

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

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

Этот документ описывает user journey создания deposit transaction в новой системе.

Flow должен покрывать создание deposit через:

  • merchant API;
  • Back Office platform admin;
  • Back Office merchant user.

Основной production flow - создание deposit через merchant API.

2. Actors ​

Merchant API Client ​

Система merchant, которая вызывает API новой платежной системы.

Platform Admin ​

Пользователь Back Office, который может создать test deposit из platform/admin context, если у него есть соответствующая permission.

Merchant User ​

Пользователь Back Office / Merchant section, который может создать deposit из merchant context, если у него есть соответствующая permission.

Customer ​

Пользователь, который открывает hosted payment form и завершает payment flow.

3. Goal ​

Создать deposit transaction, получить hosted payment URL и дать customer возможность завершить payment flow.

4. Entry Points ​

Merchant API ​

Основной endpoint:

text
POST /api/v2/deposit

Endpoint общий для всех deposit methods. Merchant не вызывает provider-specific endpoint.

paymentMethodId определяет, какой payment method configuration используется. Например, Cards, Apple Pay, Google Pay, Sofort Uber или BLIK.

Back Office ​

Back Office должен позволять создать deposit:

  • platform admin;
  • merchant user.

Для обоих случаев действие должно быть permission-based.

5. Required Request Data ​

Если merchant не передал обязательные поля, request должен быть отклонен без создания transaction.

Обязательные поля:

Merchant ​

  • merchant.id
  • paymentMethodId
  • brandId
  • transactionId
  • userId
  • webhookUrls

Redirect URLs ​

  • redirectUrl.success
  • redirectUrl.pending
  • redirectUrl.cancel
  • redirectUrl.fail

Amount ​

  • amount

Currency ​

  • currency

Customer ​

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

6. Field Rules ​

brandId ​

brandId обязателен всегда.

Даже если у merchant один brand, request должен явно указывать brand.

paymentMethodId ​

paymentMethodId - это UUID, который ссылается на configuration платежного метода.

Merchant не передает тип метода строкой вроде CARDS или BLIK. Тип метода определяется через configuration, на которую указывает paymentMethodId.

transactionId ​

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

Это не idempotency key в классическом смысле.

Если merchant повторно отправляет request с тем же transactionId, система должна вернуть ошибку, что такая запись уже существует.

7. Happy Path ​

  1. Merchant отправляет POST /api/v2/deposit.
  2. Система валидирует merchant authentication.
  3. Система проверяет обязательные поля request.
  4. Система проверяет, что transactionId еще не существует.
  5. Система проверяет, что brandId принадлежит merchant.
  6. Система проверяет, что paymentMethodId доступен для указанного brand.
  7. Система создает transaction со статусом CREATED.
  8. Система запускает routing для выбранного payment method configuration.
  9. Система определяет routing path.
  10. Система определяет MASTER MID / SUB MID GROUP / SUB MID или SUB MID AGGREGATOR.
  11. Система проверяет, какие дополнительные attributes нужны выбранному provider method.
  12. Система создает hosted payment session.
  13. Система возвращает merchant response:
    • hosted payment URL;
    • internal transaction ID;
    • merchant transaction ID;
    • status.
  14. Customer открывает hosted payment URL.
  15. Hosted payment form продолжает payment flow.

8. Response ​

При успешном создании deposit система должна вернуть:

  • hosted payment URL;
  • internal transaction ID;
  • merchant transaction ID;
  • status.

Hosted payment URL должен возвращаться всегда, если transaction была создана успешно.

status в успешном response должен быть текущим status transaction. Обычно после создания это:

text
CREATED

expiresAt в create deposit response не возвращается в MVP.

Payment session token отдельно не возвращается. Token находится только внутри hosted payment URL.

9. Initial Status ​

Сразу после создания transaction получает статус:

text
CREATED

CREATED означает, что transaction создана в системе, но customer еще не завершил payment flow.

10. Validation Errors Before Transaction Creation ​

Если merchant не передал обязательные поля, transaction не создается.

Примеры:

  • не передан brandId;
  • не передан paymentMethodId;
  • не передан transactionId;
  • не передан webhookUrls;
  • не переданы обязательные redirect URLs;
  • не передан amount;
  • не передана currency;
  • не переданы обязательные customer fields;
  • merchant authentication failed.

В этих случаях система возвращает API error без создания transaction.

11. Duplicate transactionId ​

Если merchant повторно отправляет request с уже существующим transactionId, система не создает новую transaction.

Система должна вернуть ошибку:

text
Transaction with this transactionId already exists.

Точный error code должен быть определен в error mapping / API error dictionary.

12. Routing Not Found Or Payment Method Unavailable ​

Если обязательные request fields валидны, но routing не найден или payment method недоступен, transaction создается и получает статус:

text
REJECTED

Customer должен быть перенаправлен на redirectUrl.fail.

Transaction timeline должна зафиксировать причину rejection.

13. Dynamic Attributes ​

Если merchant передал все обязательные поля для создания transaction, но выбранный SUB MID / provider method требует дополнительные attributes, система не должна отклонять create deposit request.

В этом случае:

  1. Transaction создается.
  2. Hosted payment URL возвращается merchant.
  3. Hosted payment form дособирает недостающие fields у customer.

Собирать можно любые дополнительные fields, которые нужны конкретному provider method.

Список таких fields определяется provider method requirements.

14. Status For Missing Dynamic Attributes ​

Если transaction ожидает дополнительные fields от customer на hosted payment form, нужен отдельный статус.

Рабочее название статуса:

text
WAITING_CUSTOMER_DATA

Этот статус означает, что transaction создана, но не может быть отправлена дальше в provider execution, пока customer не заполнит обязательные дополнительные fields.

Название статуса нужно отдельно утвердить в Transaction Lifecycle документе.

15. Expiration ​

Transaction должна иметь expiration.

Для MVP:

  • default expiration: 30 минут;
  • expiration time может изменяться через environment variables;
  • expiration относится к transaction, а не только к hosted payment form.

Если transaction expired на нашей стороне, она должна перейти в статус:

text
CANCELED

Expiration также может зависеть от SUB MID configuration, если такая настройка используется.

16. Webhook URLs ​

Merchant обязан передать webhookUrls при создании transaction.

Для MVP поддерживается список webhook URLs.

Если webhookUrls не переданы, request должен быть отклонен без создания transaction.

17. Redirect URLs ​

Merchant обязан передать redirect URLs:

  • success;
  • pending;
  • cancel;
  • fail.

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

Если обязательные redirect URLs не переданы, request должен быть отклонен без создания transaction.

18. Merchant Webhooks ​

Merchant webhooks отправляются:

  • на PROCESSING, если этот status пришел от provider как meaningful intermediate status;
  • на final statuses.

Final statuses:

  • COMPLETED;
  • FAILED;
  • CANCELED;
  • REJECTED.

19. Transaction Timeline ​

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

  • deposit create request received;
  • validation result;
  • transaction created;
  • initial status CREATED;
  • routing started;
  • routing result;
  • hosted payment session created;
  • hosted payment URL generated;
  • missing dynamic attributes, если есть;
  • rejection reason, если transaction стала REJECTED;
  • expiration event, если transaction стала CANCELED.

20. Acceptance Criteria ​

Use case считается реализованным, если:

  • Merchant может создать deposit через POST /api/v2/deposit.
  • Platform admin может создать deposit из Back Office при наличии permission.
  • Merchant user может создать deposit из Back Office при наличии permission.
  • brandId обязателен всегда.
  • paymentMethodId является UUID configuration платежного метода.
  • transactionId должен быть уникальным.
  • Повторный request с тем же transactionId возвращает ошибку.
  • Если обязательные fields отсутствуют, transaction не создается.
  • Если webhookUrls отсутствуют, transaction не создается.
  • Если обязательные redirect URLs отсутствуют, transaction не создается.
  • Успешный response содержит hosted payment URL, internal transaction ID, merchant transaction ID и status.
  • Успешный response не содержит expiresAt.
  • Payment session token отдельно не возвращается.
  • Успешно созданная transaction получает статус CREATED.
  • Если routing не найден, transaction создается со статусом REJECTED.
  • Если routing не найден, customer перенаправляется на redirectUrl.fail.
  • Если provider method требует дополнительные fields, hosted payment form дособирает их.
  • Если transaction ожидает дополнительные fields, используется отдельный статус, например WAITING_CUSTOMER_DATA.
  • Transaction expiration по умолчанию 30 минут и настраивается через environment variables.
  • При expiration transaction получает статус CANCELED.
  • Merchant webhooks отправляются на PROCESSING, если он пришел от provider, и на final statuses.