Mobile Api

Overview

Base conventions for integrating with the UC mobile API.

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-pair to start the optional request-encryption handshake.

Headers You Should Send

HeaderRequiredNotes
Content-Type: application/jsonYes for JSON bodiesAll examples below use JSON.
Accept-LanguageOptionalSupported examples in this documentation use en and zh. If omitted, the API falls back to English.
Authorization: Bearer <access_token>Required on protected routesMost business endpoints require this access token.
X-Agent-IDRequired for /connect/tokenAgent UUID provided by UC.
X-SignatureRequired for /connect/tokenHMAC-SHA256 signature in lowercase hex.
Device-IDOptionalUsed for device-scoped session behavior.
Device-NameOptionalReserved for client device metadata.

Response Format

Successful responses use a shared envelope:

{
    "trace_id": "",
    "status_code": 200,
    "message": "Success",
    "data": {}
}

Typical success codes:

  • 200 for reads and most mutations.
  • 201 for POST /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/token
  • POST /api/v2/auth/forgot-password
  • POST /api/v2/auth/reset-password
  • POST /api/v2/auth/logout
  • GET /api/v2/countries
  • POST /api/v2/sys/key-pair
  • GET /api/v2/sys/networks
  • GET /api/v2/info

Everything else should be treated as protected unless documented otherwise.

  1. Public Info
  2. Countries
  3. System Bootstrap
  4. Connect Token
  5. Password
  6. PIN
  7. SSO
  8. Profile
  9. Phone Management
  10. Email Management
  11. KYC
  12. Cardholder
  13. Card Request
  14. Card List
  15. Physical Cards
  16. Card Activation
  17. Card Top-Ups
  18. Card Transfers
  19. Card Withdrawals
  20. Card Transaction History
  21. Settings
  22. Payment Orders
  23. Transactions
  24. Agent Top Up Rate
  25. Agent Fund Balance
  26. Agent Fund Transactions
  27. Pushy Notifications
  28. Notification Inbox
  29. Announcements
  30. WebSocket
  31. File Upload
Copyright © 2026