API Overview
API Style
- RESTful with kebab-case naming (e.g.,
pay-ordernotpayOrder) - HTTP-based, JSON request and response bodies
API Architecture
DaxPay exposes the open Payment API:
| Tier | Path Prefix | Authentication | Response Class | Use Case |
|---|---|---|---|---|
| Payment API | /unipay/* | RSA signature | DaxResult | Server-to-server calls (pay, refund, query, close) |
Audience
Payment API is for merchant backend systems using RSA signature auth (no login session needed). Internal management endpoints used by the merchant web panel are out of scope for this documentation.
Three Categories under Payment API
/unipay/* is further divided by scenario:
| Category | Path Prefix | Scenario | Docs |
|---|---|---|---|
| Direct Pay | /unipay/pay, /unipay/close, /unipay/refund, /unipay/query/*, /unipay/sync/* | Channel & method already determined by merchant backend | Pay · Refund |
| Gateway Pay | /unipay/gateway/* | Platform cashier / aggregate QR selects the method | Gateway Pre-pay |
| Allocation | /unipay/alloc, /unipay/query/alloc-order, /unipay/sync/order/alloc | Initiate / query / sync allocation on allocatable orders | Allocate |
| Refund Query | /unipay/query/refund-order | Exact single refund lookup by refund number | Query Refund Order |
Health and Self-check
Two probe endpoints help you tell "network unreachable" from "misconfigured credentials" during early integration:
| Endpoint | Request | Auth | What it tells you |
|---|---|---|---|
/unipay/callback/ping | GET | None | Whether the service is reachable — returns a fixed marker text with no side effects; shares the channel-callback prefix, so reaching it means the callback path is open at the network level |
/unipay/ping | POST | Signed | Whether your signing setup is correct — goes through the same verification chain as business APIs (merchant identity → signature → replay protection), echoes the resolved app on success, and the response carries the platform signature so you can verify your platform public key as well |
For POST /unipay/ping, the request body only needs mchNo plus the signature fields (appId is optional and falls back to the default app). Call it before your first real business request: if it passes, your mchNo, app, private key and sign-string construction are all correct, and later errors are almost certainly business-level.
WARNING
The signed probe consumes a replay-protection nonce slot — use it for integration self-checks, not as a high-frequency health check.
Base URL
http://{your-domain}:{port}Example: https://your-domain.com (production), local dev default port 9999.
Integration Flow
- Register merchant: Get merchant number (
mchNo) and application ID (appId). - Configure keys: Generate an RSA key pair; register the merchant public key with the platform; obtain the platform public key for response verification.
- Call APIs: Construct requests with signature as defined in this documentation.
- Receive callbacks: Configure
notifyUrlto receive payment/refund result notifications.
Common Headers
| Header | Required | Description |
|---|---|---|
| Content-Type | Yes | application/json |
Signature Mechanism
Payment API (/unipay/*) uses RSA signature authentication. Signature fields are in the request body, not in headers:
| Field | Location | Description |
|---|---|---|
| sign | Request body | RSA signature value (Base64) |
| reqTime | Request body | Request time (yyyy-MM-dd HH:mm:ss, GMT+8) |
| reqId | Request body | Unique request identifier |
| nonceStr | Request body | Random string |
See Signature for details.
Response Body (Payment API)
DaxResult structure:
{
"code": 0,
"msg": "success",
"data": {},
"sign": "Base64Signature",
"resTime": "2024-12-01 20:00:00",
"reqId": "REQ20241201001"
}| Field | Type | Description |
|---|---|---|
| code | int | Status code, 0 = success |
| msg | string | Message |
| data | object | Business data |
| sign | string | RSA signature of the response (verifiable with platform public key) |
| resTime | string | Response time (Beijing time, yyyy-MM-dd HH:mm:ss) |
| reqId | string | Request ID (echoed from request) |
Field name note
Payment API uses the msg field (not message).
Conventions
HTTP Method
Trade endpoints of the Payment API all use POST with JSON body; a few auth endpoints use GET (e.g. Get User Identifier).
Date Format
All time fields of the Payment API (/unipay/**) — requests, responses and async notifications — use the Beijing time format yyyy-MM-dd HH:mm:ss, without timezone suffix:
{ "reqTime": "2024-12-01 12:00:00" }- The literal used in the platform's sign string is identical to the one in the message, so always sign the same literal (see Signature);
- Do not use ISO 8601 (e.g.
2024-12-01T04:00:00Z) or sub-second precision for request time fields, otherwise signature verification fails with20052;
Currency
All amount fields are Long in cents (fen), avoiding floating-point precision loss. Example: ¥1.00 → 100.
Status Values
Status fields are String (not numeric), using lowercase semantic codes:
- Pay status (
PayStatusEnum):wait/progress/success/close/cancel/fail/timeout - Refund order status (
RefundOrderStatusEnum):progress/success/fail/close - Refund flag (
PayRefundStatusEnum):no_refund/refunding/partial_refund/refunded
Glossary
| Term | Description |
|---|---|
| mchNo | Merchant Number |
| appId | Application ID |
| RSA Key Pair | Merchant generates RSA key pair; public key registered with platform, private key used for signing |
| method | Payment method, e.g., wechat_qr, alipay_pc (see PayMethodEnum) |
| product | Payment product (see Channel Reference) |
| orderNo | System order number |
| bizOrderNo | Merchant business order number |
| tradeNo | Trade number (one order may have multiple trade attempts) |