03.00 Golden Deposit Journey

Status: draft for discussion

1. Goal

This document describes the main end-to-end deposit journey for the MVP.

It connects the separate requirements into one business flow.

The goal is to make sure the team understands how a casino player deposit should work from merchant request to final merchant notification.

2. Actors

The journey includes:

• merchant integration;
• customer/player;
• Hosted Payment Page;
• routing;
• provider execution;
• provider callback;
• merchant webhook;
• Back Office investigation.

3. Main Flow

1. Merchant creates a deposit through the new API.
2. Merchant sends brand, payment method, amount, currency, customer data, redirect URLs, and webhook URLs.
3. The system validates whether the request has enough required data to create a transaction.
4. If required base data is missing, transaction is not created.
5. If base data is valid, transaction is created.
6. Merchant receives Hosted Payment URL and transaction identifier.
7. Customer opens Hosted Payment Page.
8. Hosted Payment Page shows loading while transaction data and routing result are prepared.
9. The system starts routing from the selected brand payment method.
10. First-level routing selects MASTER MID GROUP.
11. MASTER MID GROUP selects MASTER MID.
12. MASTER MID second-level routing selects SUB MID GROUP.
13. SUB MID GROUP selects SUB MID or SUB MID AGGREGATOR.
14. If selected execution option requires additional customer fields, Hosted Payment Page collects them.
15. The system sends the payment to the selected execution option.
16. Customer is redirected or shown the required payment action.
17. Provider sends callback.
18. The system validates callback and updates transaction status when allowed.
19. Merchant webhook is sent on PROCESSING or final status.
20. Transaction can be investigated through Back Office timeline.

4. Important Customer Experience Rules

Customer must not see:

• provider names;
• routing decisions;
• technical statuses;
• raw provider errors;
• internal rejection reasons.

Customer should see:

• loading state when payment is being prepared;
• additional fields form when required;
• clear payment action;
• clear error message if payment cannot continue;
• support reference when needed.

5. Important Merchant Experience Rules

Merchant should receive:

• transaction identifier;
• Hosted Payment URL;
• stable webhook structure;
• status updates;
• business error code and description when transaction fails or is rejected.

Merchant should not receive:

• raw provider errors;
• hidden provider names;
• internal routing attempts;
• internal platform configuration.

6. Important Platform Experience Rules

Platform users should be able to understand:

• which routing rule matched;
• which fallback was used;
• which execution options were skipped and why;
• whether provider callback was accepted, ignored, duplicated, or suspicious;
• whether merchant webhook was sent or retried;
• which configuration version was active.

7. Failure Paths That Must Be Clear

The product must clearly handle:

• missing required base data before transaction creation;
• no matching routing rule and no fallback;
• all execution options rejected by velocity limits;
• provider timeout or provider error;
• provider callback mismatch;
• duplicate provider callback;
• webhook delivery failure;
• transaction expiration;
• manual correction after final status.

8. MVP Success for This Journey

This journey is successful when the first migrated merchant can process a deposit through the new flow and the team can investigate the transaction without reading application logs.