Mini-App Backend Development

Server-side Interfaces

The common server-side interfaces are encapsulated in the MiniAppCommonService class within the public module.

@Resource
private MiniAppCommonService miniAppCommonService;

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

Before using the server-side interfaces, you need to correctly configure the Mini-App's appKey and appSecret. This configuration is mainly used when the Mini-App backend sends requests to the MOS server to sign the request parameters. The specific signing method does not require developer attention, as it is already encapsulated in the public service. After injecting the corresponding service, developers can directly call the specific method names.

Interface BaseURL

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

Interface Signature

If calling directly via HTTP, the following fields must be added to the request body (Body):

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

Signature generation rules: Sort all parameters including appKey in ascending order, then convert them into QueryString format (e.g., key1=value1&key2=value2...), append secret=appSecret at the end of the string, and finally perform MD5 encryption on this string to get the signature. The Java sample code is as follows:

import org.springframework.util.DigestUtils;

/**
 * Get signature
 *
 * @param request Request, using Object as example here, should be replaced with request body corresponding type or request base class
 * @return Signature
 */
public String getSign(Object request) {
    // Convert request to ordered TreeMap with Key in default ascending order, "appKey" also needs to 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, like 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

Obtaining Application Information

API: MiniAppCommonService.getApplication() HTTP: POST /open-apis/application/v1/getApplication

Obtain Mini-App Application Information

Parameters None

Response

Property	Type	Description
appName	String	Mini-App application name
appKey	String	Unique identifier for the application
appSecret	String	Secret key for authentication
description	String	Brief description of the application
status	Boolean	Application status
notifyUrl	String	Callback URL for authentication responses

Common Login

API: MiniAppCommonService.miniAppLogin(String code)

The universal login interface provided by the common module generates an identity token using the code and JWT obtained from the mini-program client. After creating a mini-program module, a default login interceptor com.testproject.mos.miniapp.xxx.interceptor.LoginInterceptor will be automatically included. This interceptor validates the token passed from the mini-program frontend, which should be transmitted in the Bearer token format via the HTTP header:

Authorization: Bearer <token>

After successful authentication, users can obtain the openid and language type corresponding to the logged-in user via the "Get Current User Information" interface, and then retrieve the mini-program's own user information (for this, the mini-program needs to establish its own user table, which must include a column for storing openid).

If the universal login cannot meet specific requirements, users can override the login interceptor and independently develop the login interface and the "Get Current User Information" interface.

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

Parameters

Property	Type	Required	Description
code	String	true	The code obtained via the mini-program's mos.login method

Response TokenVo

Property	Type	Description
token	String	Identity token

Get Current User Information

API: MiniAppCommonService.getMiniAppUser()

The common module provides a universal method to retrieve information of the currently logged-in user, which takes effect only when used in conjunction with the universal login interface and the default login interceptor.

Parameters None

Response MiniAppUserBo

Property	Type	Description
appKey	String	App Key
openid	String	User Unique Identifier
languageType	LanguageEnum	Language type

Exchange Code for Mos Session Information

API: MiniAppCommonService.code2session(String code) HTTP: POST /open-apis/mp/v1/auth/code2session

Obtain Mini-App Application Information

Parameters

Property	Type	Required	Description
code	String	true	The code obtained via the mini-program's mos.login method

Response MosSessionVo

Property	Type	Description
openid	String	User unique identifier
sessionKey	String	Session Key (not in use temporarily)

Payment

Before developing payment-related functionalities, it is necessary to first apply to become a Mos merchant and obtain the corresponding merchant ID (mcId), which will be required in the payment process.

Create Prepayment Orde

API: MiniAppPayService.prepay(CreatePrepayOrderAo ao) HTTP: POST /open-apis/mp/v1/pay/prepay

Create Prepayment Order

Parameters CreatePrepayOrderAo

Property	Type	Required	Description
mcId	String	true	Merchant ID
nonceStr	String	No	Random string to ensure uniqueness within the system
desc	String	No	Detailed description of the order
outTradeNo	String	true	Unique order number generated by the merchant's mini-program system
currency	String	true	Currency unit USD-Dollar | KHR-Riel
totalAmount	String	true	Total amount of the order
notifyUrl	String	true	URL for receiving payment result notifications
openid	String	true	Unique identifier of the user placing the order
expireTime	String	No	Expiration time of the order, in timestamp format (millisecond precision)

Response PrepayOrderVo

Property	Type	Description
prepayId	String	Prepayment Order ID

Query Order

API: MiniAppPayService.orderQuery(OrderQueryAo ao) HTTP: POST /open-apis/mp/v1/pay/orderQuery

Parameters OrderQueryAo

Parameters OrderQueryAo

Property	Type	Required	Description
nonceStr	String	true	Generated randomly by the merchant system to ensure request uniqueness and prevent replay attacks
outTradeNo	String	true	A unique order number generated in the merchant's own mini-program system to identify a specific order

Response OrderQueryVo

Property	Type	Description
openid	String	User unique identifier
prepayId	String	Prepayment order ID
outTradeNo	String	Merchant mini-program system order number
country	String	Country code
currency	String	Currency unit
totalAmount	String	Order amount
desc	String	Product description
status	String	Order status
expireTime	Long	Order expiration time
createTime	Long	Creation time