# SuperSDK server-side interface document
***
** Note: This document can only be used for Yoozoo games.**
## Login verification interface
### Login process
1. **The Game Client** invokes the **SuperSDK** framework **Login** interface
2. Channel login interface pops up, and the channel SDK internally initiates login request verification to the channel server.
3. User logs in successfully, and channel SDK obtains the token returned by the channel server.
4. **SuperSDK** submits the token which obtained from the channel SDK to the **SuperSDK server** for verification.
5. After receiving the data request from **SuperSDK**，the **SuperSDK server** will run the user login verification on the channel server.
6. **SuperSDK server** receives the verification result from the channel server
7. **SuperSDK server** encapsulates the channel returned information and user information (osdk_ticket)
8. **SuperSDK server** returns the encapsulated data (**osdk_ticket**) to **SuperSDK**
9. **SuperSDK** handles the encrypted data (**osdk_ticket**) to the **game client**
10. The**Game Client** forwards the encrypted data (**osdk_ticket**)to the ** Game Server**
11. The**Game Server** analyzes and verify the encrypted data, and extract the required parameters.
12. The**Game Server** sents “login successfully ” back to the client
> Note 1: The above red word steps require game integration
### Osdk_ticket parsing algorithm
1. Base64 decoding the osdk_ticket
2. Get the sign, user_id, login_sdk_name, time and other values (refer to Example 1), verify the sign and the signature obtained by the signature algorithm, where key is obtained in the configuration package tool.
> Note 2: After the game is added in the SuperSDK packaging tool, game_secret can be viewed in the game configuration.
3. Verify the generation time (time) of osdk_ticket, recomended no more than 3 minutes (180s)
4. For the signature algorithm, please see[Appendix 1: Sign Algorithm
### osdk_ticket 参数说明
| **Name of Parameters** | **Type** | **Description** |
| ---------------------- | -------- | ------------------------------------------------------------ |
| osdk_game_id | string | SuperSDK assigned game number |
| user_id | string | User unique identifier returned by 3rd Server |
| login_sdk_name | string | Third-party co-operator name |
| account_system_id | string | User account system number (user system is divided by the co-operation platform, one user account system number for each co-operation platform, the specific number can refer to the appendix 3: user account system number list) |
| osdk_user_id | string | User unique identifier, format：```osdk_user_id = account_system_id + _ + user_id``` |
| channel_id | string | Channel number |
| extend | string | Extended parameters, configured in the packaging tool |
| time | int | Sign generated timestamp |
| ip | string | IP address requested by the client |
| sign | string | ignature, signature algorithm, please see[ Appendix 1: Signature Algorithm |
```json
// 范例1：
{
"osdk_game_id": "132435",
"user_id": "837263",
"account_system_id": "0060001",
"osdk_user_id": "0060001_837263",
"login_sdk_name": "360",
"channel_id": "0",
"extend":"",
"ip": "128.1.1.10",
"time": 149382731,
"sign": "21232f297a57a5a743894a0e4a801fc3"
}
```
## Payment Process
### flow chart
1. The`Game Client` invokes the `SuperSDK` payment interface `pay`。
2. `SuperSDK` requests the `SuperSDK Server` Order interface.
3. `SuperSDK server` returns the transaction order number.
4.
5. `SuperSDK` invokes the channel SDK payment interface, the channel SDK requests the channel server to initiate payment; the channel server returns to the channel SDK, place the order successfully, and the channel SDK invokes the payment page to wait for the player to pay.
6.
7. Channel SDK requests the channel server, the player pays successfully; the channel SDK returns `SuperSDK` payment success; `SuperSDK`returns the game payment status**can not use this information to judge whether the payment is successful, the specific order status is subject to the SuperSDK server notification.**。
9.
10. he channel server asynchronously verifies the player's payment result; the channel server notifies the `SuperSDK` player that the payment is successful;
11.
12. `SuperSDK` verift the order; `SuperSDK` returns channel verification result;
13. `SuperSDK server` invokes the game delivery interface (this notification address needs to be configured by colleagues from platform)
14. `Game server ` Verify order information.
15. `Game server ` Returns the `SuperSDK server` verification result.
16. `Game server ` Notification `Game client` the result of player's payment.
> Note 3: The above red words steps require game integration
### Flowchart the seventh step interface (payment notice)
Description:
**view the payment test self-test,complete it before testing payment, communication costs can be reduced.**
Interface address:
Game's notification address consists of two parts:
1. The game notification address configured on the packaging tool (1. http://{domain}/server/pay)
2. Plus the server_url configured in the operation and maintenance system ( 2. game.youzu.com)
The final notification to the game server is: http://game.youzu.com/server/pay
HTTP request: POST
Coding: UTF-8
Request parameters:
| **Name of Parameter** | **Type** | **Must fill in** | **Description** |
| :-------------------------------------- | :------- | :--------------- | :----------------------------------------------------------- |
| order_id | string | true | superSDK order number, beginning with OS_, DS_, in some cases there may be repeated notifications, the game developer needs to de-weighted according to this field to prevent repeated diamonds. |
| coo_order_id | string | true | Third party co-operator order number |
| user_id | string | true | Third party co-operator user ID |
| op_id | int | true | The serial number of the co-operation platform is consistent with the protection of the operation and maintenance system. |
| account_system_id | string | true | User account system number (user system is divided by the co-operation platform, one user account system number for each co-operation platform; the specific number can refer to the Appendix 3: user account system number list) |
| osdk_user_id | string | true | User ID Format:```osdk_user_id=account_system_id + _ + user_id``` |
| amount | float | true | The total amount paid by the player, currency CNY |
| server_id | string | true | Game server number passed in when the App client recharges |
| product_id | string | false | Item number passed in when the App client recharges |
| product_name | string | false | Product name passed in when the App client recharges |
| game_id | integer | true | Game number passed in when the App client recharges |
| game_role_id | string | false | Game role number passed in when the App client recharges |
| pay_status | integer | true | For the game, regardless of the value of this field, you need to send the player to the game currency (diamond, gold coins), but when sey to 0 (```json {"0": "virtual payment", "1":"real payment"}```) the order will not participate in reconciliation |
| pay_time | integer | true | The UNIX timestamp of the payment which is noticed by the co-operator (from 00:00 on January 01, 1970, the total number of seconds until now |
| channel_id | string | false | Channel number |
| sdk_pay_extend | string | false | Extended parameters passed by the sdk client when recharging |
| custom_data | string | false | Channel association custom parameters |
| sign | string | true | Signature, signature verification refer to sign algorithm, please see[Appendix 1: Signature algorithm](server#签名算法)，key is game server server_key, can be obtained through the operation and maintenance game interface. |
**Request example**
>In the official environment, the signature key needs to be obtained from the operation and maintenance system.
```bash
header:
Content-type: application/x-www-form-urlencoded
body：
account_system_id=0060000
amount=6.00
channel_id=0
coo_order_id=OS_VMUMYXGRY4JJ42IY3
custom_data=2150%7C360%7Copgameid
game_id=360
game_role_id=68719487024
op_id=2150
order_id=OS_VMUMYXGRY4JJ42IY3
osdk_user_id=0060000_3507
pay_status=1
pay_time=1562071618
product_id=gold6
product_name=60%E5%85%83%E5%AE%9D
sdk_pay_extend=%7B%22level%22%3A23%2C%22opSid%22%3A%222150%22%2C%22server_id%22%3A%221652440001%22%2C%22role_id%22%3A68719487024%2C%22roleCreateTime%22%3A1561962929%2C%22server_name%22%3A%22%E5%A4%96%E7%BD%91QA1%E6%9C%8D%22%2C%22opgameid%22%3A%22opgameid%22%2C%22role_name%22%3A%22rel1%22%2C%22vip_grade%22%3A0%2C%22account%22%3A%22006
server_id=1652440001
user_id=3507
sign=db2f354bf14026f554818ca346ab39fd
key:lwKdyXCpjScn00Ny
```
### Response code
The game returns the json format result, including status and msg field
```json
{
"status":1,
"msg":"支付成功"
}
```
| status | msg |
| ------ | --------------------------- |
| 1 | payment successful |
| -1 | Signature information error |
| -2 | Product information error |
| -3 | Character information error |
| -4 | Server information error |
| -5 | Other errors |
| -6 | Duplicate order |
The game developer can modify the contents of msg to increase the accuracy of the error. Msg supports up to 100 characters
**Notification mechanism**
After recharging, the `SuperSDK server` will send `the recharge` result to the `game server` through the payment notification address only if the recharge payment is successful. After receiving the recharge notification from the `SuperSDK server`, the `game server` responds according to the processing result.
**If and only if the network request fails or status=-1 (signature error), SuperSDK Server will try to notify multiple times! ! !**
**Repeat notification**
The payment notification will be repeated, and the`game server` should prevent adding money to players multiple times due to multiple payment notifications.The`game server` can use **order_id** as the order unique identifier.
Receiving messages or duplicate notification normally, you need to return it as success. Otherwise, the `superSDK server` will determine it as unsuccess and continously sent notifications.。
The repeat notification interval is: 1 minute, 4 minutes, 9 minutes, 16 minutes, 25 minutes, 36 minutes, 49 minutes, 64 minutes, 81 minutes, 100 minutes, totally 10 times, until there is a feedback message that the reception is successful, or After 10 times of transmission, the periodic transmission is ended.
Please see Appendix 1: Signature Algorithm
### Payment notification game interface self-test tool
**Self-test tool address**：http://qt.youzu.com/Home/SuperSdk/notify
## Signature algorithm
1. All parameters are sorted in ascending alphabetical order by parameter names, and sign does not participate in sign;
2. Combine the sorted parameter name with the corresponding parameter value (non urlencode value) with &, such as: a=1, b=2, c=3 stitching to get a=1&b=2&c=3;
3. Then directly connect the key value, run a md5 operation and convert to lowercase to get the sign waitSign value.
4. Compare waitSign with the sign in the parameter, if they are the same, means successful.
5. The parameter name and the number of parameters may change. In this case, it is better not to write the parameters to constant. You can directly sign in all the parameters obtained but except sign.
6. If the value corresponding to the key is empty, do not sign it. See the example below: key:b
Example: Received data is in UTF-8 format and it has been encoded using urlencode: a=%e5%85%83%e5%ae%9d&c=1&b=&sign=5, and:key=k waitSign=md5("a= Ingot &b=&c=1k”)
Code example:
```php
function sign($data, $key)
{
ksort($data);
$str = array();
foreach ($data as $k => $v)
{
$str[] = $k . "=" . urldecode($v);
}
$strData = implode("&", $str) . $key;
return md5($strData);
}
```