English
Mock Channel: Integration Materials and API
This page is for capturing packets and building requests during integration. Materials live on the console "System → Integration Materials" page, the endpoint list on "System → API Docs"; both share one source.
Where the Materials Are
The "System → Integration Materials" page provides two things:
- Global key pair: merchant private key (sign requests) and platform public key (verify responses and callbacks);
- Gateway address: the base address used by the channel sub-app on outbound calls, default
http://127.0.0.1:10400.
The gateway uses only this global key pair. key_owner_no in a request is an ownership marker and does not switch keys; per-subject keys have been removed.
Three Signature Headers
Every gateway request and every callback carries three headers:
| Header | Content |
|---|---|
Mock-Sign | RSA signature over "timestamp + nonce + request body" |
Mock-Timestamp | Second-level timestamp; outside the time window is rejected |
Mock-Nonce | One-time random string for replay protection |
Callbacks are signed by the platform private key over the same three-line string; the channel sub-app verifies, parses, and hands them to the main app.
Message Conventions
- JSON with snake_case fields;
- Times use RFC3339;
- Amounts use the same unit as the platform (cents);
- Callbacks are plain single-layer JSON: outer
event_type/summary/out_biz_no/data, with snake_case business fields insidedata; - Callbacks return
biz_order_noandattach(only when present);biz_order_no/description/attach/app_id/expire_timein payment requests andreasonin refund requests are all stored for traceability.
Endpoint Summary
The /v3/mock/** gateway has 21 endpoints in seven families:
| Family | Endpoints |
|---|---|
| Payment | POST /v3/mock/pay, GET /v3/mock/pay/{outTradeNo}, POST /v3/mock/pay/{outTradeNo}/close |
| Refund | POST /v3/mock/refund, GET /v3/mock/refund/{outRefundNo} |
| Reconciliation | GET /v3/mock/bill |
| Split payment | POST /v3/mock/alloc, POST /v3/mock/alloc/finish, GET /v3/mock/alloc/{allocNo}, POST /v3/mock/alloc/receivers, POST /v3/mock/alloc/receivers/unbind |
| Onboarding | POST /v3/mock/onb/apply, GET /v3/mock/onb/{outApplyNo} |
| Terminals | POST /v3/mock/terminal, DELETE /v3/mock/terminal/{terminalNo}, GET /v3/mock/terminal/{terminalNo} |
| Pre-authorization | POST /v3/mock/preauth/freeze, POST /v3/mock/preauth/{authNo}/capture, POST /v3/mock/preauth/{authNo}/unfreeze, POST /v3/mock/preauth/{authNo}/cancel, GET /v3/mock/preauth/{authNo} |
Field-level definitions follow the console "API Docs" page. Transfer orders are operated in the console and have no gateway endpoint.
Error Codes
| Code | Meaning |
|---|---|
| 10013 | Mock channel merchant not registered (no such channel merchant profile on the mock side) |
| 10022 | Invalid payment code format |
| 40404 | Aggregate payment pushed to success without an actual wallet |
| 40491 | Built-in profile protected; delete / rename / change ownership / change key / enable / freeze rejected |
Reconciliation File Contract
The bill file is CSV: comma-separated, UTF-8, \n line endings, header row first.
text
tradeNo,outTradeNo,amount,status,finishTimeRun It Once from Code
Calling gateway endpoints requires signing first; the easiest way is to reuse the channel sub-app's SDK client (MockGatewayClient and friends). For pure manual debugging, read the sample messages on the console "API Docs" page, then confirm the chain works against Setup.