07.01 Merchant Deposit API

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

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

Этот документ описывает public Merchant Deposit API для MVP.

Deposit API нужен, чтобы merchant мог создать deposit transaction и получить hosted payment URL.

Merchant API должен иметь public API documentation для merchants.

Merchant-facing documentation должна быть опубликована в public documentation portal.

Owner документации:

text

Product Owner

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

Postman collection не является обязательной в MVP.

Merchants должны получить понятную документацию:

authentication/signing;
HMAC signing step-by-step;
HMAC signing examples на нескольких programming languages;
create deposit request;
create deposit response;
error response;
transaction statuses;
error codes and descriptions;
webhook payload;
webhook signature;
sandbox/test flow;
examples.

Troubleshooting section не является обязательной для MVP.

Documentation должна показывать base URLs отдельно для:

stg;
prod.

Merchant API key должен использоваться только в том environment, где он был создан.

Пример:

text

stg base URL -> stg API key
prod base URL -> prod API key

2. Endpoint

В MVP используется один endpoint:

http

POST /api/v2/deposit

Endpoint общий для всех payment methods.

Merchant выбирает конкретную merchant-level payment configuration через:

text

paymentMethodId

3. Authentication and signature

Merchant request должен быть authenticated/signed через merchant API key secret.

API key является secret value, созданным на уровне merchant.

Exact signing algorithm и signature headers должны быть предложены development/security team.

Product requirements:

request должен быть signed;
система должна проверить signature;
система должна определить merchant по API key;
revoked API key не должен работать;
during rotation grace period старый key может работать только в пределах выбранного grace period.

4. Idempotency / merchant transaction ID

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

text

transactionId

Это merchant transaction ID.

transactionId должен быть unique в рамках merchant.

Если merchant повторно отправляет request с уже существующим transactionId:

новая transaction не создается;
система возвращает duplicate transaction error;
existing transaction не изменяется.

5. Required request fields

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

paymentMethodId;
brandId;
transactionId;
userId;
webhookUrls;
redirectUrls;
amount;
currency;
customer.email;
customer.country;
customer.firstName;
customer.lastName.

Если обязательных request fields нет:

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

6. webhookUrls

Merchant должен передать список webhook URLs:

json

{
  "webhookUrls": [
    "https://merchant.example/webhook-1",
    "https://merchant.example/webhook-2"
  ]
}

Можно передать несколько webhook URLs.

Merchant webhooks отправляются на все URLs, переданные при создании transaction.

Если webhookUrls не переданы:

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

7. redirectUrls

Merchant должен передать redirect URLs:

success;
pending;
cancel;
fail.

Все redirect URLs обязательны.

Пример:

json

{
  "redirectUrls": {
    "success": "https://merchant.example/payment/success",
    "pending": "https://merchant.example/payment/pending",
    "cancel": "https://merchant.example/payment/cancel",
    "fail": "https://merchant.example/payment/fail"
  }
}

Redirect URLs передаются provider-у, если provider flow этого требует.

redirectUrls.fail также используется нашей системой, если внутренняя ошибка произошла до передачи customer в provider flow и customer уже находится на hosted payment page.

Если payment session expired, hosted payment page показывает generic expiration/error message без redirect на merchant URL.

8. Success response

При успешном создании transaction система возвращает:

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

Payment session token отдельно в response не возвращается.

Token должен быть только внутри hosted payment URL.

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

Пример:

json

{
  "transactionId": "internal-transaction-id",
  "merchantTransactionId": "merchant-transaction-id",
  "status": "CREATED",
  "hostedPaymentUrl": "https://pay.example/session/{paymentSessionToken}"
}

9. Transaction creation rules

Transaction создается только если:

request signature valid;
API key active or valid during rotation grace period;
paymentMethodId belongs to merchant;
paymentMethodId active;
brandId belongs to merchant;
all required request fields are present;
merchant transactionId is unique within merchant.

Если любое из этих условий не выполнено:

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

10. Provider-specific missing attributes

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

Обязательные request fields определяются deposit DTO, а не provider adapter schema.

Если позже routing выбрал SUB MID / SUB MID GROUP, которому нужны дополнительные provider-specific customer attributes:

transaction уже существует;
hosted payment form показывает dynamic fields;
customer заполняет missing attributes;
система сохраняет эти attributes в transaction customer context;
система продолжает provider execution.

Это отличается от missing request fields:

missing request fields = transaction не создается;
missing provider-specific customer attributes = transaction создается, hosted form дособирает данные.

Merchant всегда передает canonical field names.

Provider-specific field names не используются в public Merchant API.

11. Initial transaction status

После успешного создания transaction initial status:

text

CREATED

Routing начинается event-driven после создания transaction.

12. Error response

Merchant error response должен содержать:

unified error code;
human-readable description.

Provider raw errors не возвращаются merchant-у.

Пример:

json

{
  "errorCode": "VALIDATION_ERROR",
  "description": "Required field brandId is missing."
}

Exact error codes должны быть описаны в Error Dictionary.

13. Endpoints not included in MVP

В MVP Merchant API не содержит:

GET /deposit/{transactionId};
endpoint для manual cancel deposit;
endpoint для merchant-triggered webhook resend;
endpoint для получения списка доступных brands;
endpoint для получения списка доступных payment methods.

Transaction status/details merchant получает:

через merchant webhook;
через Back Office.

Manual cancel deposit через Merchant API не нужен.

Webhook resend доступен только из Back Office пользователям с permission.

Brands и payment methods управляются только через Back Office.

Rate limit на Merchant API в MVP не требуется.

14. Validation examples

Missing brandId

Result:

transaction не создается;
validation error.

Duplicate transactionId

Result:

transaction не создается;
duplicate transaction error.

Inactive paymentMethodId

Result:

transaction не создается;
payment method inactive/configuration error.

Missing provider-specific attribute

Result:

transaction создается;
hosted payment URL возвращается;
hosted payment form дособирает missing customer data.

15. Audit / timeline

Successful transaction creation должна создать:

transaction record;
timeline event transaction created;
routing started event, когда routing начался.

Failed validation/auth request без transaction может логироваться как API/security event, если development/security team решит это нужно.

16. Acceptance Criteria

Merchant Deposit API считается согласованным для MVP, если:

Public Merchant API documentation нужна для merchants.
Merchant documentation публикуется в public documentation portal.
Documentation owner: Product Owner.
OpenAPI spec не является обязательным merchant-facing deliverable в MVP.
Postman collection не обязательна в MVP.
HMAC request signing должен быть описан step-by-step.
HMAC request signing должен иметь examples на нескольких programming languages.
Documentation содержит transaction statuses.
Documentation содержит error codes and descriptions.
Documentation содержит sandbox/test flow.
Troubleshooting section не обязательна в MVP.
Documentation содержит stg/prod base URLs.
API key является environment-local.
Endpoint один: POST /api/v2/deposit.
Merchant request подписывается через API key secret.
Exact signing format определяет development/security team.
transactionId обязателен.
transactionId unique в рамках merchant.
Duplicate transactionId не создает новую transaction.
Required request fields включают paymentMethodId, brandId, transactionId, userId, webhookUrls, redirectUrls, amount, currency, customer.email, customer.country, customer.firstName, customer.lastName.
webhookUrls поддерживает несколько URLs.
redirectUrls success/pending/cancel/fail обязательны.
Success response содержит internal transaction ID, merchant transaction ID, status, hosted payment URL.
expiresAt не возвращается в create deposit response.
Payment session token отдельно не возвращается.
Token находится только внутри hosted payment URL.
GET /deposit/{transactionId} не входит в MVP.
Manual cancel endpoint не входит в MVP.
Merchant-triggered webhook resend endpoint не входит в MVP.
Brands/payment methods list endpoints не входят в MVP.
Rate limit на Merchant API не требуется в MVP.
Missing required request fields не создают transaction.
Missing provider-specific customer attributes дособираются на hosted payment form после создания transaction.
Initial transaction status после создания: CREATED.
Error response содержит unified error code + description.

17. Open Questions

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

Technical/security follow-up:

Определить exact request signing algorithm.
Определить exact signature headers.
Определить timestamp/replay protection rules.
Описать exact JSON schema.
Описать exact duplicate transaction error behavior/status code.

07.01 Merchant Deposit API ​

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

2. Endpoint ​

3. Authentication and signature ​

4. Idempotency / merchant transaction ID ​

5. Required request fields ​

6. webhookUrls ​

7. redirectUrls ​

8. Success response ​

9. Transaction creation rules ​

10. Provider-specific missing attributes ​

11. Initial transaction status ​

12. Error response ​

13. Endpoints not included in MVP ​

14. Validation examples ​

Missing brandId ​

Duplicate transactionId ​

Inactive paymentMethodId ​

Missing provider-specific attribute ​

15. Audit / timeline ​

16. Acceptance Criteria ​

17. Open Questions ​

07.01 Merchant Deposit API

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

2. Endpoint

3. Authentication and signature

4. Idempotency / merchant transaction ID

5. Required request fields

6. webhookUrls

7. redirectUrls

8. Success response

9. Transaction creation rules

10. Provider-specific missing attributes

11. Initial transaction status

12. Error response

13. Endpoints not included in MVP

14. Validation examples

Missing brandId

Duplicate transactionId

Inactive paymentMethodId

Missing provider-specific attribute

15. Audit / timeline

16. Acceptance Criteria

17. Open Questions