03.05 Provider Callback Handling

Status: draft for discussion

1. Goal

The system must correctly accept provider callbacks and update transaction status.

At the same time, merchant must not see internal provider details.

2. Expected Behavior

Provider callback flow must:

• accept callback quickly;
• save the fact that callback was received;
• verify that callback belongs to the correct transaction;
• verify amount and currency;
• verify that callback matches the selected execution path;
• avoid applying duplicate callback more than once;
• ignore but record provider statuses that are not supported by the business in transaction timeline;
• mark suspicious callbacks for investigation.

3. Which Provider Webhooks Affect Transaction

Transaction can be affected by:

• COMPLETED;
• FAILED;
• CANCELED;
• PROCESSING.

If provider sends another status, the system stores it for investigation but does not change the transaction to an unsupported status.

4. Duplicate and Suspicious Callbacks

Duplicate callback must not break the transaction.

Suspicious callback must not change the transaction in an unsafe way.

Platform users must see the investigation reason.

5. Merchant Visibility

Merchant users do not see raw provider data or raw provider error.

Merchant sees only the final business result.