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 |
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) |