.. _8 Payment system: 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: - 1. Log in to the developer platform and register a Pico member (http://developer.pico-interactive.com/) - 2. Apply to become a developer 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. - 3. 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: .. image:: _static/8.1.png Figure 8.1 Merchant ID - 4. 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: .. image:: _static/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: .. image:: _static/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. - 5. 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: .. image:: _static/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: .. image:: _static/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.2 Other related interfaces ------------------------------------ 8.2.1 Register ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Pico provides developers with Oauth2.0-based authentication and authorization, therefore, the users need to log in before paying, and here the Pico Payment Login node or Pico Login SDK node we provide should be used: .. image:: _static/unsigned_7131.png or .. image:: _static/unsigned_71310.png - Callback functions: The parameters of OnPicoLogInOutCallback are as follows: .. image:: _static/unsigned_7132.png - IsSuccess: Whether the login and logout are successful (boolean), true means success, and false means failure - Reason: Reasons for successful or login and logout failures For the login part, the login can be executed only once, then the payment can be directly used, the login expiration time is about two weeks, and after the expiration, the payment interface will be provided with a return code (login expiration code), and it will be successful after the user only logs in again. 8.2.2 Logout ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/unsigned_7211.png - Function performance: Logout - Its callback function: OnPicoLogInOutCallback has been introduced above. 8.2.3 Payment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/unsigned_7231.png - Function performance: Pay in P currency - Input parameter Order: .. image:: _static/unsigned_7232.png - OrderNumber: The characters of the order number defined by the merchant itself are within 32, which may contain letters and numbers; - OrderTitle: Order title; - ProductDetail: Product detail; - Notify Url: The URL to be notified (not required) must be a directly accessible url and cannot be provided with parameters; - PicoCoinCount: Paid Amount in P currency. - Callback function On Pico Pay Order Callback .. image:: _static/unsigned_7233.png Code and Msg are as follows: ============================ ================================================== code Message ============================ ================================================== 00000 Network anomaly 10000 Log-in is successful 10001 User not logged in 10002 Please enter the correct amount 10003 Log-in has been expired, please re-log in 11000 Merchant verification successful 11001 Merchant authentication failed 11002 User authentication parameter is wrong or request has been expired 11003 Merchant is not verified 12000 Payment is successful 12001 Payment failure 12003 P currency is insufficient 12004 Balance available 13000 The order is generated 13001 Get acquisition failure 13002 The order generation failure 14000 The order query is successful 14001 There is no order / the order is wrong 14002 The user cancels payment operation 15000 The product information is not entered 15001 The prepaid ID is not entered 15002 Please enter the Pico payment order number or merchant order number NOAUTH The merchant does not have the interface permission SYSTEMERROR The system is wrong APP_ID_NOT_EXIST There is no APP_ID MCHID_NOT_EXIST MCHID There is no MCHID APP_ID_MCHID_NOT_MATCH App_id and mch_id are mismatched LACK_PARAMS The parameters are lacked SIGNERROR The signature is wrong NO_DATA No data is found / the user does not recharge ORDER_EXIST There has been an order PAY_CODE_NOT_EXIST There is no consumption code PAY_CODE_EXIST The user has consumed the product code ============================ ================================================== .. image:: _static/unsigned_7241.png - Function performance: Pay with a payment code - Input parameter Order: .. image:: _static/unsigned_7242.png - OrderNumber: The characters of order number generated by the merchant itself are within 32, which may contain letters and numbers; - OrderTitile: Order title; - Product Detail: Product detail: - Notify Url: The URL to be notified (not required) must be a directly accessible url and cannot be provided with parameters; - PicoPayCode: I.e., product code, which can be get by the user through the 8.1.1 in-game payment configuration. - Callback function: On Pico Pay Order Callback, same as payment in P currency. 8.2.4 Order query ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/unsigned_7251.png - Function performance: Order query - Input parameter Order Number: Order number (string): - Callback function On Pico Query Order Callback .. image:: _static/unsigned_7252.png - The parameter meaning is the same as OnPicoPayOrderCallback 8.2.5 Get user information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/unsigned_7221.png or .. image:: _static/unsigned_72211.png - Function performance: Get user information - Callback function On Pico Get User Info Callback .. image:: _static/unsigned_7222.png - Info: An unprocessed Json string. Here is an example of a successful query: .. code-block:: java {"ret_code":"0000", "data" : { "aboutme":"", "birthday" : 1460476800000, "phone" : "13100000000", "username" : "Admin", "email" : "", "gender" : "male", "lastname" : "", "openid" : "4f3148bdc34d9bca104927729a173b64", "firstname" : "", "avatar" : "http://172.31.83.11/upload/6dd6ee103714e967846c3d38ae48d511", "signature" : "14a25d7219d8dfc91e55f63286ae5c0a", "country" : "China", "city" : "" }, "ret_msg": a. "Successful call" } The query failure example is as follows: .. code-block:: java { "ret_code":"00003000", "ret msg": "Signature verification failure". } List of other ret_code codes and ret_msg: Table 8.1 On Pico Get User Info Callback output parameter ret_code code and ret_msg list ====================== ============================================== ret_code ret_msg ====================== ============================================== 0000 Successful request 00020000 Database operation failure 9999 System error 00001000 Parameter error 00002000 Data parsing failure 00003000 Signature verification failure 00003001 Time verification failure 00060000 User not found 00060001 User password error 00060002 Unknown user login error 00061000 User token finding failure 00061001 User token verification failure 00061002 Unknown user token error 00070001 Application verification failure 00071001 Application key verification failure 00080001 OAUTH_CODE verification failure 00090001 REFRESH_TOKEN verification failure 00100001 ACCESS_TOKEN verification failure 00110001 SCOPE verification failure ====================== ============================================== 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 .. image:: _static/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: .. code-block:: java /** * result: Map collection of gotten data * paykey: i.e. the paykey on the developer platform. */ public static String createSign(Map 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); }