This article explains how to integrate the payment interface of the Miracle Games Android SDK in the Unity engine to launch the payment method selection window and receive payment callbacks.
● When initiating a payment call, an order number is generated in the developer's system and then passed to the payment interface via the comment parameter.
● After the payment process is completed, the Miracle Games server will launch a callback to the developer, which contains the comment information, through which the developer can mark the order number as a successful payment.
● When multiple in-game items share the same price point, there's no need to create individual products for each item in the Miracle Games backend. Instead, a single universal product can be established. When calling the payment interface, pass the item ID to the comment parameter. Upon payment completion, Miracle Games will deliver this comment parameter directly to the developer. Developers can then distribute the corresponding items based on this parameter.
● When the game server receives the callback notification from the MG server, it needs to use the product_tag parameter to compare with the game order information, or use the product_price_usd parameter to compare with the price of the props to check, and then the props will be released if it passes the check. product_tag parameter is an attribute that is maintained by the background of the developer. The name of the attribute is"custom_tag"，, and it is recommended to store the ID of the product, MG server will pass the value of this attribute to the game server after url encoding.
● If the developer doesn't have a server, he can receive the callback event through the client to complete the game props issuance.
sequenceDiagram
Game->>+Game Server: click on the top-up slot, the game server stores the order information
Game Server->>+Game: return order information
Game->>+MG SDK: call MG payment window (with order information)
MG SDK->>+MG Server: select payment channel, store order information in MG Server
MG Server->>+3rd party payment: initiate order request
3rd party payment->>MG Server: asynchronous callback notification, update order status on MG server
%%Note over MG Server, Game: server side callback notification
Par Server-side callback notification
MG Server->>+Game Server: asynchronous callback notification, update game server order status (return Success)
Game Server->>+Game: Placement of props
end
%%%Note over MG Server,Game:Client Callback Notification
par Client callback notification
MG SDK->>+MG Server:Check Order Status
MG Server->>+MG SDK:return successful order information
MG SDK->>+Game: client callback notification, drop props
Game->>+MG SDK: call report order cancellation interface
MG SDK->>+MG Server: write off the order.
end
Interface Description:
Calling this interface opens the platform's payment interface. A payment callback message is sent when the user's payment is complete or canceled.
Method Definition:void payPurchase(String goodskey, String comment, String callbackId)
Parameter Description:
goodskey: Product Key, generated by MiracleGames when creating a product.
comment: custom parameter, urlencode before passing, will return the parameter to the developer as is after completing the payment.
callbackId: payment callback id, generated when creating the callback address. After the payment is completed, MiracleGames will call the url corresponding to this ID to notify the developer of the payment result.
Example of an interface call:
public void Pay() {
using (AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) {
using (AndroidJavaObject jo = jc.GetStatic("currentActivity")) {
jo.Call("payPurchase", "93C97BDFF86AF61", "comment", "");
}
}
} After the player's payment is complete, Miracle Games will call back the developer based on the application callback address created by the developer on the Miracle Games Developer Platform (Ref.), which notifies the developer server of the payment result as a parameter in the form of a GET request.
For the complete server-to-server callback procedure and decryption process, please refer to（Section 4: Post-Payment Callback to Developer Server）
If the game has a server to receive callbacks, then there is no need to access this function, directly access the server side of the payment callback.
Before accessing the client-side callback, you need to configure the game type identifier in the Activity, and set it to "true" to indicate a single-player game.
Example:
<!-- Game type representation -->
<meta-data
android:name="SINGLE_GAME"
android:value="true" > <!--true for single player games false for online games-->
</meta-data>Interface Description: For single-player games without servers, players need to make client-side callbacks after successful payment and send props to write off the order.
Method Definition:void onAssetsChange(string message)
Parameter Description:
The message parameter value is: "xx,xx,xx,xx,xx,xx..." . Separated by commas.
The first value is the product order number
The second value is a user-defined parameter, assigned by the user when initiating a payment, and originally returned after a successful payment.
The third value is the name of the product
The fourth value is the number of items
The 5th value is the commodity label
Example:
void onAssetsChange(string message)
{
Debug.Log("===onAssetsChange : " + message);
string[] temp = message.Split(new char[] { ',' });
if (temp != null && temp.Length >= 0)
{
string product_id = temp[0]; //MG order number
string comment = temp[1]; //customize the passthrough parameter
string goodsNam = temp[2]; //goods name
string goodsNum = temp[3]; //number of goods
string goodsTag = temp[4]; //goods tag
Debug.Log("Sending props");
ReportAssestFulfillment(product_id);//write off the order after props are sent out
}
}If the game has a server to receive the callbacks, there is no need to access this feature, and you can directly access the payment callbacks on the server side.
Interface Description: After sending props to the user, you need to call this interface to write off the asset order, otherwise every initialization will send the client information about the order, prompting that it has not been written off.
Method Definition:void ReportAssestFulfillment(String id)
Example:
void ReportAssestFulfillment(string id)
{
using (AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer"))
{
using (AndroidJavaObject jo = jc.GetStatic("currentActivity"))
{
jo.Call("ReportAssestFulfillment", id);//id: merchandise order number, the first parameter value returned by the asset change client callback
}
}
}