03.05 Provider Callback Handling

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

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

Этот документ описывает обработку callbacks/webhooks от providers.

Provider callback flow должен:

• принимать callbacks через приватный endpoint;
• максимально скрывать реальные provider names из схем и URLs;
• валидировать callback по правилам конкретного provider;
• сохранять raw callback payload;
• обрабатывать callback асинхронно через queue/event;
• маппить provider status на internal transaction status;
• защищать final statuses от автоматических изменений;
• сохранять ignored/rejected/duplicate callbacks для investigation;
• создавать merchant webhook events при PROCESSING и final statuses.

2. Endpoint Strategy

В старой системе callbacks обычно принимались через endpoint вида:

/api/v1/provider-callback/{provider}

В новой системе реальные provider names должны быть максимально скрыты из endpoints, Swagger/OpenAPI schemas.

Цель: если Swagger/OpenAPI schema случайно будет exposed, реальные названия providers не должны стать видимыми.

Варианты, которые нужно рассмотреть development team:

• provider hash вместо реального provider name;
• opaque callback route identifier;
• SUB MID / callback configuration token;
• другой provider-agnostic identifier.

Пример product expectation:

/api/v2/provider-callback/{callbackRouteId}

где callbackRouteId не раскрывает real provider name.

Финальный технический подход должна предложить development team.

Product requirement: real provider name must not be exposed in callback URL or API documentation. Exact hiding strategy is development team responsibility.

3. Architecture Principle

Provider callback endpoint не должен выполнять весь processing синхронно.

Expected flow:

1. Callback gateway принимает callback.
2. Система выполняет минимальную первичную validation.
3. Callback сохраняется.
4. Создается event / queue message.
5. Processing service асинхронно обрабатывает callback.

Цель:

• быстро ответить provider;
• не терять callbacks;
• иметь возможность retry processing внутри нашей системы;
• не блокировать external callback endpoint долгой бизнес-логикой.

4. Callback Validation

Validation зависит от provider, но система обязана иметь callback validation layer.

Минимальные проверки:

• provider-specific signature / auth validation, если provider это поддерживает;
• transaction exists;
• callback относится к выбранному SUB MID / SUB MID AGGREGATOR;
• amount matches transaction;
• currency matches transaction;
• callback is not duplicate;
• provider status может быть mapped;
• callback payload имеет ожидаемую структуру.

Если конкретный provider требует дополнительные проверки, они должны быть реализованы в provider adapter / callback handler code.

5. Raw Callback Storage

Raw provider callback payload нужно сохранять.

Raw payload нужен для:

• support investigation;
• audit/debug;
• dispute analysis;
• provider integration debugging.

Raw payload должен быть виден только platform/support users с соответствующими permissions.

Merchant users не должны видеть raw provider callback payload.

6. Invalid Callback

Если callback не прошел validation, например invalid signature или invalid payload:

• callback сохраняется как rejected callback;
• transaction status не меняется;
• если transaction известна, в timeline можно сохранить validation failed event;
• если transaction неизвестна, callback остается в rejected callback storage / operational logs;
• response to provider зависит от validation policy конкретного provider.

Rejected callback должен быть доступен для platform investigation.

7. Duplicate Callback

Если provider прислал duplicate callback:

• transaction status не меняется;
• duplicate event сохраняется в transaction timeline;
• raw payload сохраняется;
• callback помечается как duplicate.

Система не обязана поддерживать отдельную provider retry idempotency/deduplication логику сверх определения duplicate callbacks в рамках processing.

8. Callback After Final Status

Если provider прислал callback после того, как transaction уже находится в final status:

• transaction status не меняется;
• event сохраняется в transaction timeline как ignored;
• raw payload сохраняется.

Это важно для investigation, потому что provider может прислать late callback или повторный callback.

9. Unknown Provider Status

Если provider прислал status, который не mapped в нашей системе:

• transaction status не меняется;
• event сохраняется в transaction timeline как ignored;
• raw payload сохраняется.

Alert на unknown provider status не обязателен по текущему MVP decision, но metric должна быть.

10. Amount / Currency Mismatch

Если callback содержит amount/currency, которые не совпадают с transaction:

• transaction status не меняется;
• callback сохраняется как suspicious / ignored;
• raw payload сохраняется;
• в transaction timeline создается suspicious/ignored event;
• должен быть создан alert для platform/operations.

Это потенциально критичный кейс, потому что callback может относиться к неправильной transaction или указывать на provider/integration issue.

11. Provider Status Mapping

Provider status mapping в MVP реализуется на уровне кода.

UI для provider status mapping не входит в MVP.

Система обрабатывает provider callback statuses:

• PROCESSING
• COMPLETED
• FAILED
• CANCELED

Unknown statuses сохраняются как ignored.

12. PROCESSING Callback

Если provider прислал status, который mapped в PROCESSING:

• transaction status становится PROCESSING;
• source status change = provider_callback;
• status change сохраняется в transaction timeline;
• merchant webhook отправляется на PROCESSING.

Важно: PROCESSING ставится и отправляется merchant только если он пришел от provider как meaningful intermediate status.

Система не ставит PROCESSING после того, как просто отправила request в provider.

13. COMPLETED Callback

Если provider прислал completed status:

• transaction status становится COMPLETED;
• source status change = provider_callback;
• status change сохраняется в transaction timeline;
• merchant webhook создается и отправляется.

Redirect behavior остается на стороне provider flow.

14. FAILED Callback

Если provider прислал failed status:

• transaction status становится FAILED;
• source status change = provider_callback;
• status change сохраняется в transaction timeline;
• merchant webhook создается и отправляется.

15. CANCELED Callback

Если provider прислал canceled status:

• transaction status становится CANCELED;
• source status change = provider_callback;
• status change сохраняется в transaction timeline;
• merchant webhook создается и отправляется.

16. Callback Before Transaction Ready

Возможна ситуация, когда callback пришел до того, как provider request handling полностью завершился.

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

• callback нужно сохранить;
• callback нужно обработать позже;
• transaction status не должен потеряться;
• timeline должен позволять понять порядок событий.

Development team должна предложить точный mechanism для deferred callback processing.

17. Response To Provider

Provider callback endpoint должен отвечать provider OK, если callback был принят gateway и поставлен в очередь.

В MVP мы принимаем callbacks и кладем их в queue, а полная validation и processing выполняются асинхронно.

Даже если позже callback окажется invalid, rejected, duplicate, unknown или suspicious, это должно быть обработано внутри нашей системы через callback processing flow, timeline, logs, metrics и alerts.

Цель:

• быстро отвечать provider;
• не провоцировать лишние provider retries;
• не блокировать provider callback endpoint долгой validation/business logic;
• не терять callback payload.

18. Timeline Events

Transaction timeline должна поддерживать events:

• callback received;
• callback validation started;
• callback validated;
• callback validation failed;
• provider status mapped;
• status changed;
• callback ignored;
• duplicate callback ignored;
• callback after final ignored;
• unknown provider status ignored;
• suspicious amount/currency mismatch;
• callback queued;
• callback processed.

19. Status Change Source

Каждое изменение transaction status из provider callback должно иметь source:

provider_callback

Для investigation нужно сохранять:

• previous status;
• new status;
• provider status;
• mapped status;
• source;
• timestamp.

20. Metrics And Alerts

Метрики по provider callbacks:

• callbacks received;
• callbacks accepted;
• callbacks rejected;
• invalid callbacks;
• duplicate callbacks;
• unknown provider statuses;
• callbacks after final status;
• suspicious amount/currency mismatch;
• callback processing latency;
• callback queue lag;
• callback processing errors.

Alerts:

• amount/currency mismatch;
• spike invalid callbacks;
• spike unknown provider statuses;
• callback processing lag too high;
• callback processing errors.

21. Acceptance Criteria

Provider callback handling считается реализованным для MVP, если:

• Callback endpoint не раскрывает real provider name в публичном URL.
• Callback endpoint быстро принимает callback, сохраняет его и кладет event в queue.
• Callback validation layer существует.
• Callback validation проверяет transaction, SUB MID/SUB MID AGGREGATOR, amount, currency и duplicate.
• Raw callback payload сохраняется.
• Invalid callback сохраняется как rejected callback.
• Duplicate callback сохраняется в timeline как duplicate.
• Callback after final сохраняется в timeline как ignored.
• Unknown provider status сохраняется в timeline как ignored.
• Amount/currency mismatch сохраняется как suspicious/ignored и создает alert.
• Provider status mapping реализован в коде.
• PROCESSING callback ставит status PROCESSING.
• PROCESSING callback отправляет merchant webhook.
• COMPLETED callback ставит COMPLETED и отправляет merchant webhook.
• FAILED callback ставит FAILED и отправляет merchant webhook.
• CANCELED callback ставит CANCELED и отправляет merchant webhook.
• Status changes из callbacks имеют source provider_callback.
• Callback before transaction ready сохраняется и обрабатывается позже.
• Metrics по callbacks доступны.