Skip to content

Mock Channel: Integration Materials and API ​

Updated: 11/10/26, 10:51:10 AM

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:

HeaderContent
Mock-SignRSA signature over "timestamp + nonce + request body"
Mock-TimestampSecond-level timestamp; outside the time window is rejected
Mock-NonceOne-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 inside data;
  • Callbacks return biz_order_no and attach (only when present); biz_order_no / description / attach / app_id / expire_time in payment requests and reason in refund requests are all stored for traceability.

Endpoint Summary ​

The /v3/mock/** gateway has 21 endpoints in seven families:

FamilyEndpoints
PaymentPOST /v3/mock/pay, GET /v3/mock/pay/{outTradeNo}, POST /v3/mock/pay/{outTradeNo}/close
RefundPOST /v3/mock/refund, GET /v3/mock/refund/{outRefundNo}
ReconciliationGET /v3/mock/bill
Split paymentPOST /v3/mock/alloc, POST /v3/mock/alloc/finish, GET /v3/mock/alloc/{allocNo}, POST /v3/mock/alloc/receivers, POST /v3/mock/alloc/receivers/unbind
OnboardingPOST /v3/mock/onb/apply, GET /v3/mock/onb/{outApplyNo}
TerminalsPOST /v3/mock/terminal, DELETE /v3/mock/terminal/{terminalNo}, GET /v3/mock/terminal/{terminalNo}
Pre-authorizationPOST /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 ​

CodeMeaning
10013Mock channel merchant not registered (no such channel merchant profile on the mock side)
10022Invalid payment code format
40404Aggregate payment pushed to success without an actual wallet
40491Built-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,finishTime

Run 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.