8 Payment system

Pico payment is a game currency payment system based on the Pico account system, and the settlement method is based on the current game currency unit under Pico (P currency). If the project requires internal purchasing function, please read the contents of this chapter carefully. If the project does not require internal purchasing function, please ignore this chapter.

8.1 Preparations

8.1.1 Get the string used for payment

When developer accesses the payment SDK, an application needs to be created on the developer platform and the corresponding string should be gotten. The application process is as follows:

The developers are divided into individual developers and enterprise developers, please apply according to the actual situations. After the review is submitted, we will provide feedback within 3 working days, please view the status of the developer platform in time.

    1. View merchant ID

After applying to become a developer, click the nickname in the upper right corner to view the developer ID, which will serve as the unique symbol of the merchant in the payment system:

_images/8.1.png

Figure 8.1 Merchant ID

    1. Get the corresponding string

Developers can enter the application creation phase from the management center. After clicking Create Application, first select the platform to publish:

Then enter the corresponding platform to perfect the relevant information of application:

_images/8.2.png

Figure 8.2 Information about application improvement

Please pay key attention to the red position of the above figure, please fill out the application type carefully, and it can’t be modified once you fill it out! If there is a case of external payment of props for game applications, we require the developers to use the way of adding product code in the background of developers for unified management.

Description of payment methods:

Currently, there are two payment methods: one is P currency payment (application type) and the other is product code payment (game type). Only one payment method can be used for the same application.

After the application is successfully created, the developer platform will assign a string to it, including APP ID, APP KEY and APP Secret. The developers will also be assigned a developer ID:

_images/8.3.png

Figure 8.3 APP ID, APP KEY, APP Secret

And then select “In-game payment configuration” and configure the game’s internal purchase information:

Attention should be paid that the rule of the product code is defined as follows: ‘the first letter is a letter, only the entry of letters and numbers is allowed, and it should not be more than 20 characters’. The product code between different props cannot be repeated. The prop types are divided into consumable prop and non-consumable prop. Consumable prop are reusable commodities, such as gold currency, blood bottle, etc. Non-consumable props are disposable purchased products, such as weapons and unlocking levels.

    1. Fill in the strings

Go to Edit->Project Settings…, expand PicoMobile under the Plugins sub-item, check “Enable Payment Module”, then select “Is Foreign” according to the actual situations, and finally get the merchant (developer) ID, APPID, APP KEY., APP secret and fill them in the following location:

_images/8.7.png

Figure 8.4 String filling

8.1.2 Set the callback proxy event

Before using payment, the callback proxy event should be set first, so that you can get the parameters output by the callback functions and set the subsequent execution flow. Here, please use the PicoPaymentSetCallbackDelegates node we provide:

_images/unsigned_7121.png

Among them, On Pico Payment Exception Callback is a callback for various exceptions from payment, and the exact meaning of the other callback function parameters will be introduced in the next section which introduces its related main callback functions.

8.3 Developer server interaction

After the payment is completed, the payment system will send the relevant payment results and user information to the merchant, and the merchant needs to receive and process them and return a response.

When the background notifies the interaction, if the receiving of the merchant’s response by the payment system receives is not successful or overtime, the notification should be considered as failed, and the payment system will periodically re-initiate the notification through certain policies to maximize the success rate of the notification, but it may not guarantee that the notification will be eventually successful.

The same notification may be sent to the merchant system repeatedly and the merchant system must be able to process duplicate notifications correctly. The recommended practice is to firstly check the status of the corresponding service data when it receives and processes the notification, and determine whether the notification has been processed, it should be re-processed if it has not been processed, and the result return will be successful directly if it has been processed. Before the status check and processing of business data, data locks should be used for concurrency control to avoid data confusion caused by function reentry.

The merchant server needs to implement the following interface for receiving the request from the Pico server and get the payment result and user information of the Pico payment system:

Table 8.2 Interfaces that the merchant server needs to implement

Name Payment results callback interface
Request Type POST
Request URL Pay, parameter notify_url transmitted by PayOrder
Request Format JSON
Return Format JSON
Is login required Yes
Request Parameters For details, see “Table 8.3 Notification parameters in payment results notification”
Return parameter _images/unsigned_7253.png

For details see “Table 8.4 Return results”
Return parameter example { “ret_code”:”SUCCESS”, “ret_msg”:”OK”}
Update instruction  

Table 8.3 Notification parameters in payment results notification

Field Name Param Name Required Type Description
Return Status Code ret_code Yes String SUCCESS/FAIL This field is the communication identifier, rather than transaction identifier,and if the transaction is successful should be determined based on the check on result_code.
Return Message ret_msg No String Return error information if not empty, the cause could be Signature failure and parameter format check error.
Error Code sub_code No String Error code
Error code description sub_msg No String Wrongly returned information error
Pico pay order number trade_no Yes String Pico payment order number
Merchant order number out_trade_no Yes String The order number within the merchant system
App ID app_id Yes String Application APP_ID approved by the platform
Merchant ID mch_id Yes String Assigned merchant number for payment
User ID open_id Yes String Unique identifier of the user under the merchant appid
Device ID device_id No String Terminal device number
Random string nonce_str Yes String Random string: no longer than 32 bits. Recommended random number generation algorithm
Signature signature Yes String For signature, see the signature generation algorithm
Business Result result_code Yes String SUCCESS/FAIL
Transaction type trade_type Yes String Payment type
Currency Type fee_type Yes String Currency type
Total amount total_fee Yes String Total order amount
Paid-in amount receipt_fee Yes String Paid-in amount
The amount paid by the buyer buyer_pay_fee No String The amount paid by the buyer
Voucher or Discount coupon_fee No String Voucher or discount
Merchant data package attach No String Merchant data package, returned as it is
Payment completion time pay_time Yes String Payment completion time, in the format: yyyy-MM-dd HH: mm:ss

Table 8.4 Return results

Field Name Param Required Type Description
Status code returned ret_code Yes String SUCCESS/FAIL, SUCCESS indicates that the merchant has received and verified the notification successfully.
Return information ret_msg No String Return error information if not empty, the cause could be Signature failure and parameter format check error.

Special remarks: The signature verification must be performed for the contents of the payment result notification in the merchant system to prevent “false notification” due to data leakage and capital loss.

The signature verification rule is as follows:

  1. Remove the signature parameter from the returned list of parameters, and simultaneously add key = “app_secret”, value=paykey, then sort it naturally according to the key value, separate the multiple parameters with &, and finally take MD5 encryption
  2. Compare the encrypted string with the get signature

The signature function is as follows:

/**
* result: Map collection of gotten data
* paykey: i.e. the paykey on the developer platform.
*/

public static String createSign(Map<String, Object> result, String paykey)
{
        if (result == null || result.size() == 0)
                return null;
        result.put("app_secret", paykey);
        String sign = result.get("signature");
        result.remove("signature");
        String[] tmp = new String[result.size()];
        int i = 0;
        for (String key : result.keySet())
        {
                tmp[i++] = key;
        }
        Arrays.sort(tmp);
        String sign = "";
        for (String string : tmp)
        {
                if (m.get(string) == null)
                        continue;
                sign += string + "=" + URLEncoder.encode(m.get(string).toString()
                        , "utf-8") + "&";
        }
        if (sign.endsWith("&"))
                sign = sign.substring(0, sign.length() - 1);
        Log.i(TAG, "createSign: " + sign);
        String localSign = MD5.MD5(sign);
        return localSign.equal(sign);
}