Technical Instructions
Last updated:2025-04-29 18:40:52
About this document
This document provides guidance on selecting the appropriate payment solution for different in-game purchase scenarios, as well as offers key recommendations for developers building payment services. We look forward to working together with developers to enhance players' payment experience.
Terms
Virtual items: Virtual items within the game, used to enhance the gaming experience or provide additional in-game services. Examples include weapons, equipment, and resources.
Console: The management console accessed by developers after logging in with their mini game account.
Process description
1. Development process
1.1 Payment
In-game payment scenarios include two categories: game currency and direct virtual item purchase. Currently, only direct virtual item purchase is supported.
Direct virtual item purchase
Players purchase in-game items directly using online payment. For example, purchasing weapons, equipment, resources, and other items within the game.
1.2 Payment capabilities
Direct virtual item purchase capability
This allows players to buy items directly using online payment. Super App as a Service (SAS) (openServer) notifies the developer’s backend to deliver the item via a reliable callback. Developers can use wx.requestMidasPaymentGameItem to provide players with an entry for purchasing items. Once payment is successful, Super App as a Service (SAS) pushes an item delivery notification (mini_game_pay_goods_deliver_notify) to the developer's server, instructing the developer to deliver the item.
2. Recommendations for using the mini game payment feature
2.1 Use the direct virtual item purchase feature in direct purchase scenarios
Item delivery for direct purchases is initiated when Super App as a Service (SAS) (openServer) sends a notification to the developer. Normally, after a successful payment, a server-side message will be pushed to the developer. In rare cases, there may be some notification delay. Notes:
1. The same delivery request (outTradeNo) may be sent multiple times due to network issues. We will attempt to deliver at least once within a limited time, until a successful delivery response is received.
2. For duplicate requests, developers must ensure that each order is fulfilled only once, and the response to repeated requests should be the same as the first successful delivery.
3. Notification intervals: 15s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h.
4. Mini game developers must configure push notifications in the console under Commercialization - Virtual payment - Basic configurations, and enable the item delivery push under Commercialization - Virtual payment - Virtual item management to receive the callback request. For details, see Direct Purchase of Mini Game Items.
Requirements
Delivery notifications will be sent to the developer’s server as promptly and reliably as possible. In the event of network issues or unsuccessful responses, retries will occur. The developer’s server may receive duplicate delivery notifications (i.e., the same order ID is pushed multiple times). Developers must ensure idempotency in item delivery—each order ID (outTradeNo) should only result in one delivery, even if notified multiple times.
The delivery notification channel must implement proper request validation and secure key management to prevent malicious third-party requests due to key leakage.
2.2 General recommendations
2.2.1 Server API domain selection
Developers can choose the optimal domain for API integration based on their server deployment (lower latency, higher stability). Other domains can be used for disaster recovery. If a network issue occurs, consider switching to a backup domain. Always use domain names for API requests—do not use IP addresses. For payment-related services, prioritize local access and implement a robust domain failover strategy.
2.2.2 Recommendations for access_token
To ensure security, do not expose the AppSecret used to obtain the access_token, nor the access_token itself, outside of the game client or server. For the method of obtaining the access_token, see Mini program server.
2.2.3 Notes on login session and session_key (signature)
Payment-related APIs that involve user signatures (the signature parameter) require the use of session_key. The session_key is assigned by the Super App as a Service (SAS) server (openServer) while the player is using the mini game. It serves as a credential for identity verification and secure communication between the superapp backend and the game server, acting as the key for encrypting and signing user data. The session_key is stored separately on the Super App as a Service (SAS) server (openServer) and the game server. When calling wx.login, a new session_key may be generated. To ensure consistency, developers should use the code obtained from wx.login to fetch the latest session_key.
Notes:
For implementing the login process, refer to Mini Program Login Practical Tutorial. The session_key is primarily used for identity verification between the Super App as a Service (SAS) server (openServer) and the game server. For authentication between the game frontend and backend, developers should implement their own custom login session. You may use the session_key’s validity period as your own login session, or implement a custom expiration strategy.
For data security, the developer’s server should never send the session_key to the mini game client or expose it externally.
When calling wx.login, the user’s session_key may be refreshed, invalidating the old one (there is a minimum refresh interval; repeated calls in a short time may not always refresh the session_key).
The session_key currently expires on a daily basis.Developers must maintain the latest session_key on their server.
Avoid frequent calls to wx.login. This API typically accesses backend system resources, so limit its frequency to protect the system and prevent abuse.The mini game frontend should control the frequency of wx.login calls and prohibit repeated automatic retries in a short period.Use local storage to track call status. If repeated login attempts are detected, prompt the player with a dialog to retry, restart the mini program, or clear the cache. Developers should also set up alerts to detect and troubleshoot such issues in their code. Trigger a login (wx.login) in any of the following cases:
First-time login.
The session_key stored on the game server has expired (e.g., payment API returns -15012 [signature error] or -15015 [session key expired]); notify the frontend to re-initiate the wx.login process. The backend can use checkSessionKey for verification.
The game's custom login session expires.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback