03.06 Merchant Webhooks

Status: draft for discussion

1. Goal

Merchant must receive notifications about important transaction changes.

2. When Webhooks Are Sent

Webhooks are sent:

• on PROCESSING;
• on final statuses.

Final statuses:

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

3. Webhook URLs

Merchant sends webhook URLs when creating the transaction.

If there are several URLs, the system sends a notification to each of them.

Manual resend uses the same URLs that were provided when the transaction was created.

4. What Merchant Receives

Webhook must have a stable structure for all statuses.

Merchant must receive:

• transaction identifiers;
• status;
• amount and currency;
• merchant/customer reference;
• business error information if the transaction ended with an error.

Raw provider data is not sent.

Merchant metadata is not sent in the MVP.

5. Delivery and Retry

If delivery fails, the system must retry webhook delivery.

Retries must be visible in transaction details.

Manual resend is available to users with the required business access.

Exact retry intervals and delivery rules are proposed by the development team.

6. Reliability Expectations

Webhook delivery is critical because merchant systems rely on it to update customer deposit state.

The product must make it clear:

• which webhook was sent;
• to which URL it was sent;
• which status was sent;
• whether delivery succeeded;
• whether retry is still in progress;
• whether manual resend happened.

Duplicate delivery should not be treated as a new transaction event by the business.

Exact idempotency and signing rules are proposed by the development team.