Overview
Base URL
All application routes are mounted under:
/api/v2
Token issuance for third-party clients now uses the same mobile API host:
- Mobile API base:
<MOBILE_API_BASE_URL>/api/v2 - Connect token route:
POST /api/v2/connect/token
There is no separate token-service base URL required for this flow.
A key bootstrap endpoint in this integration is:
POST /api/v2/sys/key-pairto start the optional request-encryption handshake.
Headers You Should Send
| Header | Required | Notes |
|---|---|---|
Content-Type: application/json | Yes for JSON bodies | All examples below use JSON. |
Accept-Language | Optional | Supported examples in this documentation use en and zh. If omitted, the API falls back to English. |
Authorization: Bearer <access_token> | Required on protected routes | Most business endpoints require this access token. |
X-Agent-ID | Required for /connect/token | Agent UUID provided by UC. |
X-Signature | Required for /connect/token | HMAC-SHA256 signature in lowercase hex. |
Device-ID | Optional | Used for device-scoped session behavior. |
Device-Name | Optional | Reserved for client device metadata. |
Response Format
Successful responses use a shared envelope:
{
"trace_id": "",
"status_code": 200,
"message": "Success",
"data": {}
}
Typical success codes:
200for reads and most mutations.201forPOST /api/v2/auth/register.
trace_id exists in the payload schema, but it may be empty on successful responses.
It is more consistently useful on error payloads.
Important Error Handling Note
Most HTTP error responses are currently returned with an HTTP transport status of 200,
while the real failure code is inside the JSON body as status_code.
Handle failures using the response payload, for example:
{
"status_code": 401,
"message": "Authentication required",
"trace_id": "2a6d1a45d8c9402d",
"data": null
}
Optional Encrypted Payload Wrapper
Some auth routes and write endpoints also accept the encrypted wrapper format. That means you can send either:
- Plain JSON with the business fields directly.
- An encrypted wrapper that the server decrypts before validation.
Encrypted wrapper shape:
{
"key_version": "c2f1d9a4",
"salt": "base64-salt",
"data": "base64-ciphertext"
}
Any extra top-level fields outside that wrapper are merged back into the decrypted payload.
Bootstrap the encryption session
Use POST /api/v2/sys/key-pair before sending encrypted data.
Request:
{
"key": "client-public-key"
}
Response:
{
"trace_id": "2a6d1a45d8c9402d",
"status_code": 200,
"message": "Success",
"data": {
"server_pub_key": [12, 44, 91, 7],
"key_version": "c2f1d9a4"
}
}
Public vs Protected Routes
For client token issuance, use:
POST /api/v2/connect/token
The following routes are public:
POST /api/v2/connect/tokenPOST /api/v2/auth/forgot-passwordPOST /api/v2/auth/reset-passwordPOST /api/v2/auth/logoutGET /api/v2/countriesPOST /api/v2/sys/key-pairGET /api/v2/sys/networksGET /api/v2/info
Everything else should be treated as protected unless documented otherwise.
Recommended Reading Order
- Public Info
- Countries
- System Bootstrap
- Connect Token
- Password
- PIN
- SSO
- Profile
- Phone Management
- Email Management
- KYC
- Cardholder
- Card Request
- Card List
- Physical Cards
- Card Activation
- Card Top-Ups
- Card Transfers
- Card Withdrawals
- Card Transaction History
- Settings
- Payment Orders
- Transactions
- Agent Top Up Rate
- Agent Fund Balance
- Agent Fund Transactions
- Pushy Notifications
- Notification Inbox
- Announcements
- WebSocket
- File Upload