Mini-App Backend Development

Interface Description

The common server-side interfaces are encapsulated in the MiniAppCommonService service class from the public module. You can obtain an instance by injecting this service class. Usage example:

@Resource
private MiniAppCommonService miniAppCommonService;

@Resource
private MiniAppPayService miniAppPayService;
    
ApplicationVo application = miniAppCommonService.getApplication();
// ...

Before using the server-side interfaces, you must correctly configure the Mini-App's appKey and appSecret. These are mainly used for signing request parameters when the Mini-App backend initiates requests to the Mos server. Developers do not need to concern themselves with the specific signing method — the public service has already encapsulated it. After injecting the corresponding service, you can directly call the specific methods.

Interface BaseURL

• Test environment: https://mos-test.mos.me
• Production environment: https://mos.mos.me

Interface Signature

If calling directly via HTTP, the request Body must include the following fields:

• appKey: Mini-App App Key
• sign: Signature

Signature generation rule: Sort all parameters (including appKey) in ascending order, convert them to QueryString format (e.g., key1=value1&key2=value2...), then append secret=appSecret at the end, and finally perform MD5 on the resulting string. Java example code:

import org.springframework.util.DigestUtils;

/**
 * Get signature
 *
 * @param request Request object (Object used here as example; replace with actual request type or base class)
 * @return Signature
 */
public String getSign(Object request) {
    // Convert request to a key-ordered TreeMap (ascending by default), "appKey" must be included
    Map<String, String> requestSortedMap = JSON.parseObject(JSON.toJSONString(request), new TypeReference<TreeMap<String, String>>() {
    });
    requestSortedMap.put("appKey", "<your_app_key>");

    // Convert request to QueryString format, e.g., key1=value1&key2=value2...
    StringBuilder qsBuilder = new StringBuilder();
    for (Map.Entry<String, String> entry : requestSortedMap.entrySet()) {
        // "sign" or empty values do not participate in signing
        if ("sign".equals(entry.getKey()) || entry.getValue() == null || entry.getValue().isEmpty()) {
            continue;
        }
        qsBuilder.append(entry.getKey()).append("=").append(entry.getValue().trim()).append("&");
    }
    // Append "secret=your_app_secret" at the end
    qsBuilder.append("secret=").append("<your_app_secret>");

    // MD5 processing
    return DigestUtils.md5DigestAsHex(qsBuilder.toString().getBytes(StandardCharsets.UTF_8));
}

Login & Authentication

Get Application Information

API: MiniAppCommonService.getApplication()

HTTP: POST /open-apis/application/v1/getApplication

Get Mini-App application information

Parameters

None (signature still required)

Response

Field	Type	Description
appName	String	Application name
appKey	String	Application key
appSecret	String	Application secret
description	String	Application description
status	Boolean	Application status
notifyUrl	String	Callback URL

Universal Login

API: MiniAppCommonService.miniAppLogin(String code)

A universal login interface provided by the public module. It uses the code obtained from the Mini-App frontend and JWT to generate an identity token. After creating a new Mini-App module, a default login interceptor com.testproject.mos.miniapp.xxx.interceptor.LoginInterceptor is included. This interceptor validates the token passed from the Mini-App frontend in the format of Bearer token via HTTP Header:

Authorization: Bearer <token>

After authentication passes, users can retrieve the logged-in user's openid and language type via the "Get Current User Information" interface, which can then be used to fetch the user's information within the Mini-App itself (the Mini-App must maintain its own user table with a column storing openid).

If the universal login does not meet your needs, you may override the login interceptor and implement your own login and current user information retrieval interfaces.

Note: Do not modify the code in the public module.

Parameters

Field	Type	Required	Description
code	String	Yes	Code obtained via mos.login in Mini-App

Response TokenVo

Field	Type	Description
token	String	Identity token

Get Current User Information

API: MiniAppCommonService.getMiniAppUser()

A universal method provided by the public module to get the current logged-in user. It works only when used with the universal login interface and the default login interceptor.

Parameters

None (signature still required)

Response MiniAppUserBo

Field	Type	Description
appKey	String	Application key
openid	String	User unique identifier
languageType	LanguageEnum	Language type

Exchange Code for Mos Session

API: MiniAppCommonService.code2session(String code)

HTTP: POST /open-apis/mp/v1/auth/code2session

Get Mos session information using code

Parameters

Field	Type	Required	Description
code	String	Yes	Code obtained via mos.login in Mini-App

Response MosSessionVo

Field	Type	Description
openid	String	User unique identifier
sessionKey	String	Session key (currently unused)

QR Code Login

Generate QR Code

HTTP: POST /open-apis/mp/v1/auth/getLoginQrCodeUrl

Generate a QR code for Mini-App scan-to-login. Expires in 120 seconds. The Mini-App uses this string to generate the QR code image.

Request Body

None (signature still required)

Response Body

Field	Type	Description
qrCode	String	QR code string, format: https://mos.me/miniapp-open/login/{uuid}
uuid	String	QR code UUID string

Check QR Code Status

HTTP: POST /open-apis/mp/v1/auth/getLoginQrCodeStatus

Check the status of the QR code. Returns user information upon successful scan.

Request Body

Field	Type	Required	Description
qrCodeUuid	String	Yes	QR code UUID string

Response Body

Field	Type	Description
status	String	'NO_SCAN': Not scanned | 'SCAN': Scanned
mosOpenUserVo	MosOpenUserVo	User info (available only after successful scan)

Response MosOpenUserVo

Field	Type	Description
openId	String	User unique identifier
firstName	String	First name
lastName	String	Last name
headPortrait	String	Avatar URL

Payment

Before developing payment features, you must apply to become a Mos merchant and obtain the corresponding merchant ID (mcId), which is required in the payment flow.

Create Prepayment Order

API: MiniAppPayService.prepay(CreatePrepayOrderAo ao)

HTTP: POST /open-apis/mp/v1/pay/prepay

Create a prepayment order

Parameters CreatePrepayOrderAo

Field	Type	Required	Description
mcId	String	Yes	Merchant ID
nonceStr	String	No	Random string, must be unique in the system
desc	String	No	Order description
outTradeNo	String	Yes	Merchant Mini-App system order number
currency	String	Yes	Currency: USD - US Dollar | KHR - Cambodian Riel
totalAmount	String	Yes	Order amount
notifyUrl	String	Yes	Callback URL
openid	String	Yes	User unique identifier
expireTime	String	No	Order expiration timestamp (milliseconds)

Response PrepayOrderVo

Field	Type	Description
prepayId	String	Prepayment order ID

Merchant Pays User

API: MiniAppPayService.payToMiniAppUser(PayToMiniAppUserAo ao)

HTTP: POST /open-apis/mp/v1/pay/payToMiniAppUser

Call this interface to pay a user

Parameters PayToMiniAppUserAo

Field	Type	Required	Description
nonceStr	String	No	Random string, must be unique in the system
outTradeNo	String	Yes	Merchant Mini-App system order number
currency	String	Yes	Currency: USD - US Dollar | KHR - Cambodian Riel
amount	String	Yes	Payment amount
openid	String	Yes	User unique identifier

Response PayToMiniAppUserVo

Field	Type	Description
prepayId	String	Prepayment order ID
nonceStr	String	Random string
outTradeNo	String	Merchant Mini-App system order number
paymentNo	String	Mos order number

Query Order

API: MiniAppPayService.orderQuery(OrderQueryAo ao)

HTTP: POST /open-apis/mp/v1/pay/orderQuery

Query order status

Parameters OrderQueryAo

Field	Type	Required	Description
nonceStr	String	Yes	Random string, must be unique in the system
outTradeNo	String	Yes	Merchant Mini-App system order number

Response OrderQueryVo

Field	Type	Description
openid	String	User unique identifier
prepayId	String	Prepayment order ID
outTradeNo	String	Merchant Mini-App order number
country	String	Country code
currency	String	Currency
totalAmount	String	Order amount
desc	String	Product description
status	String	Order status
expireTime	Long	Expiration time
createTime	Long	Creation time

Customer Service Account

Create Customer Service Account

HTTP: POST /open-apis/mp/v1/customerServ/create

Create a customer service account

Request Body

Field	Type	Required	Description
openid	String	Yes	User unique identifier
name	String	Yes	Customer service name

Response Body

Field	Type	Description
token	String	Unique identifier of the customer service account (used in subsequent requests)

Send Message via Customer Service Account

HTTP: POST /open-apis/mp/v1/customerServ/{token}/sendMessage

Send a message to a specified user via the customer service bot

Path Parameter

Field	Type	Required	Description
token	String	Yes	Customer service account identifier

Request Body

Field	Type	Required	Description
openid	String	Yes	Recipient user unique identifier
content	ContentAo	Yes	Message content, see ContentAo

ContentAo

Field	Type	Required	Description
text	String	Yes	Message text

Response Body

None