English
Mock Channel: Architecture
This page covers four things: which processes make up the chain, how requests flow, which two protocol surfaces are exposed, and where data is stored. It does not cover code structure or class design.
Component Boundaries
The Mock Channel does not face the main app directly. It stands behind the channel sub-app and plays the "third-party payment platform" role:
| Role | Responsibility | Not responsible for |
|---|---|---|
| Main app | Wires the daxpay-channel-mock orchestration module, maintains channel merchants and routing, receives callbacks and advances orders | Does not call the mock service directly |
| Channel sub-app | Translates platform requests into gateway messages per the channel protocol; verifies signatures, parses responses and callbacks | Does not hold mock data |
| Mock Channel | Emulates transaction results, stores orders with full records, sends callbacks by rule, provides the console | Does not connect to a database or MQ, does not touch real channels |
Why not let the main app call it directly
The mock service follows an "open API style" gateway contract (RSA mutual signing, replay-protection headers, snake_case messages), matching how real channels talk to the channel sub-app. With the channel sub-app making outbound calls, mock validates signing, message fields, and callback parsing instead of just returning a fixed code.
Two Protocol Surfaces
| Protocol surface | Called by | Authentication | Purpose |
|---|---|---|---|
/v3/mock/** | Channel sub-app (main integration chain) | RSA public/private key mutual signing + replay protection (Mock-Sign / Mock-Timestamp / Mock-Nonce) | 21 gateway endpoints for payment, refund, split payment, pre-authorization, reconciliation, onboarding and terminals |
/mock/ui/api/** | Console pages | Console login (default mock/mock, can be disabled) | Order search, manual decisions, rule configuration, data generation, data reset |
Both endpoint types return Cache-Control: no-store; static assets do not carry the header, so a CDN in front caches them as usual. The endpoints used by payer-facing standalone pages (payment confirmation, mock payment, payment code) are allowed anonymously.
The gateway uses only one global key pair: the merchant private key signs requests, the platform private key signs responses and callbacks. Copy the materials from the console "System → Integration Materials" page. A request may carry key_owner_no, but it is only an ownership marker; signature validation still uses the global public key.
Data and Capacity
- All data lives in a single SQLite file (default
data/mock-channel.db, override withmock.db-path), WAL mode, connection pool of 2; the parent directory is created on startup; - Schema scripts are idempotent and run on every startup; orders / rules / callback records do not reset on restart;
- Capacity limits are configurable: 5,000 payment orders, refund orders, and split allocations each, 2,000 callback records; overflow evicts the oldest by creation time;
- To return to a clean state, delete the three
data/mock-channel.db*files and restart (back to the two built-in seeds + default rules); the console's "Clear All Data" clears transaction data only, leaving profiles and rules untouched.
It does not connect to PostgreSQL, Redis, or MQ, so it runs as a single process on any development machine.
Production Safeguards
Production safeguards live on the main app side, not on the mock side:
- The
daxpay-channel-mockorchestration module is conditionally wired by deployment mode; a main app started in PROD mode does not wire it at all (beans not registered); - If routing still points at mock channel merchants, placing an order fails fast with "product strategy does not exist" instead of succeeding silently;
- The panel's demo mode cleans up demo containers when switching back to a production deployment.
"Intranet" does not make the console safe
The console can force order changes and resend callbacks; once reachable from outside, it hands out the power to decide payment results. Bind it to an intranet address or localhost only — never put it on a public domain "for convenience".
Design Constraints
| Constraint | Reason |
|---|---|
| Single-file storage, zero external dependencies | The integration environment starts, stops, and resets at will without consuming a middleware stack |
| Decision chain collapsed to "default success + per-subject overrides" | Global bypass (all success / all failure) is easy to leave switched on and silently fails whole batches; removed |
| Only one rule table, for split payment | Split payment is query-only with no callback, so rules are its only automatic decision mechanism; other transactions rely on manual decisions and per-subject overrides |
| Callbacks are plain single-layer JSON + three signature headers | Easy to capture and troubleshoot while still validating signatures |
| Built-in profiles are structurally locked | The two direct/ISV profiles in the seed anchor demos and tests; deleting or renaming them is forbidden so one-click demos keep working |