API Overview
API Style
- RESTful with kebab-case naming (e.g.,
pay-ordernotpayOrder) - HTTP-based, JSON request and response bodies
Two-Tier API Architecture
DaxPay exposes two API tiers with different authentication and response formats:
| Tier | Path Prefix | Authentication | Response Class | Use Case |
|---|---|---|---|---|
| Payment API | /unipay/* | RSA signature | DaxResult | Server-to-server calls (pay, query, close) |
| Management API | /mch/* | Sa-Token session | Result | Merchant web panel operations (refund, list, sync) |
Key distinction
Payment API is for merchant backend systems using RSA signature auth (no login session needed). Management API is for the merchant web panel using Accesstoken header (Sa-Token session).
Three Categories under Payment API
/unipay/* is further divided by scenario:
| Category | Path Prefix | Scenario | Docs |
|---|---|---|---|
| Direct Pay | /unipay/pay, /unipay/close, /unipay/query/*, /unipay/sync/* | Channel & method already determined by merchant backend | Pay |
| Gateway Pay | /unipay/gateway/* | Platform cashier / aggregate QR selects the method | Gateway Pre-pay |
| Channel Auth | /unipay/assist/channel/auth/* | Fetch user openId/userId via OAuth | Generate Auth URL |
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 |
| Accesstoken | Management API only | Sa-Token session token (only for /mch/* endpoints; not needed for Payment API /unipay/*) |
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-01T12:00:00Z",
"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 (UTC, ISO 8601) |
| reqId | string | Request ID (echoed from request) |
Field name note
Payment API uses msg field. Management API (Result) uses message.
Conventions
HTTP Method
Payment API endpoints use POST with JSON body. Management API query endpoints use GET, operation endpoints use POST.
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) |