.1 Summary
Usually, game developers do not only launch their games on one channel. The more channels they access, the more users they may acquire, but it also means more workload for accessing the SDK, duration and costs. For a game to have enough users, it even needs to access more than 30 various channels to ensure its market coverage.
It takes 3 days to complete a single SDK access process with an experienced full-time client program, a full-time server programmer, and a full-time QA. Therefore, when a product faces 30 or more channel SDKs with different requirements, the cost of personnel and time will increase dramatically. So we need a common interface to handle the needs of various channels, which is the unified channel SDK access framework. This part mainly provides the interface specifications for the interaction between the platform SDK server and the CP game server
1.2 Basic payment process
1.2.1 Channel payment process
The game client requests the server to generate an internal order every time the user clicks to buy. And it is necessary to adopt a specific mechanism (such as prohibiting continuous clicks to purchase within a certain period of time) to prevent frequent user operations from causing excessive load on the server.
All internal orders generated by the game server need to be stored for review. And after receiving the external order returned by the channel, it will process the shipping operation asynchronously and notify the client to update the data display through a specific mechanism.
The channel payment interface is responsible for completing currency transaction operations, generating and storing external orders for use in reconciliation queries.
When the SDK server forwards the request, an additional order log data is stored, including the internal order number, external order number and order status, for reference when reconciling accounts and finding bugs.
1.2.2 General channel payment flow chart
1.3 Protocol description
1.3.1 Communication protocol
The SDK server uses the HTTP protocol as the communication protocol, and the game server initiates an interface request to the SDK server by constructing an HTTP request (POST method).
1.3.2 Data protocol
1. Data format
Both the content of the request message and the response message use JSON to represent the data.
2. Character encoding
Both the request and the corresponding content are encoded in UTF-8 characters
3. Signature rules
Both the signature in the request and the response are done using md5 hash, the algorithm is as follows:
MD5(signature content + "|" + apiKey)
illustrate:
·MD5 uses the RFC1321 standard and needs to be converted to all lowercase after encoding.
·In the expression describing the signature, "+" means string connection, which does not exist in the actual generated string to be signed.
·Signature content refers to the concatenation of several fields in the request data of each interface. The basic format is that each field value is separated by a "|" symbol and then directly connected. Note that since the "|" symbol is used to separate fields, this symbol needs to be avoided in the signature content, and special symbols such as line breaks (carriage return or line feed) also need to be removed in advance. If the corresponding field is empty, the "|" symbol still needs to be reserved.
·When calculating the MD5 signature, the byte value of the string should be obtained in UTF8 encoding.
·appid and apiKey are assigned by the packaging tool, please refer to the documentation for how to use the packaging tool.
4. Signature example
Suppose the request data is:
“data:{
“id” : 123,
“name” : “test”
“value” : “something”
“other” : “blarblar”
}
The required signature content is:
id + name + value
After concatenation, the content string to be signed is obtained as
123|test|something
Assuming apiKey=aabbcc, the string that needs to be MD5 hashed is:
123|test|something|aabbcc
1.4 Interface description
1.4.1 User session authentication
1. Request URL: http://TypeSDK:PORT/{appid}/{channelid}/Login/
Note: {appid} in the URL represents the game code, which is generated by the packaging tool, and {channelid} represents the channel code. For the list of channel codes, please refer to the description of the packaging tool, and the current channel code can be obtained from the parameters submitted by the client.
Example: http://192.168.0.1:40000/1000/1/Login/
2. Call method: HTTP POST
3. Interface description:
Verify user login results.
A) The game client obtains user login information through the login action of the SDK client.
B) The game client sends the obtained user login information to the game server.
C) The game server sends the user login information to the SDK server through this request to verify whether the login information is valid.
D) The SDK server returns the verification result and other information for use by the game server.
4. Requester: game server
5. Responder: SDK server
6. Request content ( JSON format):
| Field Name |
field description |
type |
Remark |
| id |
unique user ID |
string |
The user ID of the corresponding channel. It is not required to pass, and an empty string is passed if there is no specification. |
| token |
User login session ID |
string |
This login ID. It is not required to pass, and an empty string is passed if there is no specification. |
| data |
Additional Information |
JSON |
Additional Information. It is not mandatory. The meaning of this field is different depending on the channel. If no explanation is given, an empty string is passed. |
| sign |
signature parameters |
string |
MD5(signature content + "|" + apiKey) Signature content: Id + ”|” + token + ”|” + data |
7. Return content ( JSON format):
| Field Name |
field description |
type |
Remark |
| code |
response code |
int |
The result flag of this request |
| id |
unique user ID |
string |
User ID of the corresponding channel |
| nick |
The nickname of the user in the channel |
string |
User nickname corresponding to the channel |
| token |
User login session ID |
string |
This login ID |
| msg |
response message |
string |
If an error occurred with the request, describe the error message. |
| value |
channel return information |
JSON |
The original result information returned by the channel. |
Response code description:
0: The channel returns normally, and the result is successful
1: The channel returns normally, but the result fails
2: Channel server request error
-1: The submitted request parameter is wrong
-2: The submitted request is converted into a channel parameter error
-3: The signature of the submitted request parameter is wrong
-99: unknown error
id, nick, token Description:
Depending on the return fields defined by different channels, these three fields do not necessarily have values. When the channel does not return the corresponding field, the field value is an empty string.
1.4.2 Recharge result callback
1. Request address:
This address is the recharge result notification address, which is submitted by the game server to the SDK server through the notifyurl field in the SaveOrder interface below.
2. Call method: HTTP POST
3. Interface description:
Notify the user of the recharge result.
A) The user submits a recharge request to the SDK client in the game.
B) The SDK client forwards the recharge request to the channel party
C) The channel party executes the top-up asynchronously.
D) The channel party sends the recharge result to the SDK server
E) The SDK server sends the recharge result to the game server through this interface.
F) The game server processes the recharge logic.
G) The game server returns the processing result to the SDK server.
H) The SDK server returns the processing result to the channel party.
4. Requester: SDK server
5. Responder: game server
6. Request content ( JSON format):
| Field Name |
field description |
type |
Remark |
| code |
response code |
int |
The recharge result returned by the channel. |
| id |
unique user ID |
string |
The user ID of the corresponding channel. |
| order |
Channel order number |
string |
The order number returned by the channel. |
| cporder |
CP order number |
string |
The internal order number sent by the game client when submitting an order. If the channel does not accept this parameter, this field is an empty string. |
| info |
Order Additional Information |
string |
Additional information sent by the game client when submitting an order. If the channel does not accept this parameter, this field is an empty string. |
| sign |
signature parameters |
string |
MD5(signature content + "|" + apiKey) Signature content: code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info |
| amount |
order amount |
string |
The amount of the order value converted into RMB (in cents) is used for server-side verification and does not participate in the signature. |
7. Return content ( JSON format):
| Field Name |
field description |
type |
Remark |
| code |
response code |
int |
The result flag of this request |
| msg |
response message |
string |
If an error occurred with the request, describe the error message. |
Response code description:
0: return normally, the result is successful
1: normal return, the result fails
-99: unknown error
8. Recommended treatment
After receiving the request, the game server can save the request parameters, and then return code=0, indicating that the message was received successfully. Afterwards, the recharge or item distribution logic is processed asynchronously.
1.4.3 Submission of recharge information
1. Request address: http://TypeSDK:PORT/{appid}/{channelid}/SaveOrder/
Note: {appid} in the URL represents the game code, which is generated by the packaging tool, and {channelid} represents the channel code. For a list of channel codes, please refer to the documentation of the packaging tool, and the current channel code can be obtained from the parameters submitted by the client.
Example: http://192.168.0.1:40000/1000/1/SaveOrder/
2. Call method: HTTP POST
3. Interface description:
The recharge information is on file for further investigation.
A) The user submits a recharge request to the game server in the game.
B) The game server generates an internal recharge order number and related recharge information
C) The game server returns the internal recharge order number and related recharge information to the game client for submission to the channel party.
D) The game server asynchronously sends the internal recharge order number, the order callback url and related recharge information to the SDK server.
E) The SDK server archives the recharge information for further investigation and returns the processing result.
4. Requester: game server
5. Responder: SDK server
6. Request content (JSON format):
| Field Name |
field description |
type |
Remark |
| cporder |
CP order number |
string |
The internal order number sent by the game client when submitting an order. |
| data |
order information |
string |
Additional information customized by CP when order is generated, cannot be empty or empty string. |
| sign |
signature parameters |
string |
MD5(signature content + "|" + apiKey) Signature content: cporder + ”|” + data |
| notifyurl |
Order callback url |
string |
This order callback notifies the url of the game server and does not participate in the signature. |
| verifyurl |
order query url |
string |
The url to query the details of the order from the game server does not participate in the signature. |
7. Return content (JSON format):
| Field Name |
field description |
type |
Remark |
| code |
response code |
int |
The result flag of this request |
| msg |
response message |
string |
If an error occurred with the request, describe the error message. |
Response code description:
0: normal return, archived successfully
1: normal return, archive failed
-1: system error
-2: parameter error
-3: signature verification error
-99: unknown error
Note: The SaveOrder interface is requested when the server generates an internal order number. Only when the request is successfully returned can the client be allowed to perform subsequent recharge actions.
1.4.4 Recharge Information Confirmation
1. Request URL: http://TypeSDK:PORT/{appid}/{channelid}/CheckOrder/
Note: {appid} in the URL represents the game code, which is generated by the packaging tool, and {channelid} represents the channel code. For a list of channel codes, please refer to the documentation of the packaging tool, and the current channel code can be obtained from the parameters submitted by the client.
Example: http://192.168.0.1:40000/1000/1/CheckOrder/
2. Call method: HTTP POST
3. Interface description:
Recharge information query.
A) SDK服务端向游戏服务端转发充值结果回调。
B) 游戏服务端向SDK发送充值信息查询请求，目的是确认该充值结果有效性。
C) SDK服务端根据提交的内部充值订单号查询充值信息并返回游戏服务端。
D) 游戏服务端根据查询结果进行逻辑处理。
说明：部分渠道提供信息查询接口，本接口将优先使用渠道的信息查询接口处理请求。如果该渠道没有提供信息查询接口，则查询 3.3.3 充值信息提交 接口中保存的充值信息，如果创建充值信息时没有调用该接口，或者没有查询到目标订单对应的充值信息，则会返回未查询到相应充值信息。
4.请求方：游戏服务端
5.响应方：SDK服务端
6.请求内容（JSON格式）：
| 字段名称 |
字段说明 |
类型 |
备注 |
| cporder |
CP订单号 |
string |
游戏客户端在提交订单时传送的内部订单号。 |
| sign |
签名参数 |
string |
MD5(签名内容 + ”|” + apiKey) 签名内容： cporder |
7.返回内容（JSON格式）：
| 字段名称 |
字段说明 |
类型 |
备注 |
| code |
响应码 |
int |
本次请求结果标志 |
| msg |
响应信息 |
string |
如果请求出错，描述错误信息。 |
| value |
订单详细信息 |
JSON |
根据渠道不同，返回相应订单信息。 |
响应码说明：
0：正常返回，获取订单信息成功
1：正常返回，没有获取到订单信息
2：正常返回，获取订单信息错误
-1：系统错误
-2：参数错误
-3：签名校验错误
-99：未知错误
1.4.5 游戏订单查询
1.请求地址：
该地址为订单查询地址，在SaveOrder接口中通过verifyurl字段提交至SDK服务端。
2.调用方式：HTTP POST
3.接口描述：
SDK服务端向游戏服务端查询收到的订单信息。
A) 用户在游戏中向SDK客户端提交充值请求。
B) SDK客户端将充值请求转发渠道方
C) 渠道方异步执行充值。
D) 渠道方将充值结果发送给SDK服务端
E) SDK服务端通过该接口向游戏服务端查询该充值请求是否合法。
F) 游戏服务端处理查询逻辑。
G) 游戏服务端向SDK服务端返回查询结果。
H) SDK服务端比对订单信息并依此确定下一步处理流程。
4.请求方：SDK服务端
5.响应方：游戏服务端
6.请求内容（JSON格式）：
| 字段名称 |
字段说明 |
类型 |
备注 |
| code |
操作类型 |
string |
预留字段，区分本次查询操作类型。目前统一传0 |
| id |
用户唯一标识 |
string |
对应渠道的用户ID。 |
| order |
渠道订单号 |
string |
渠道返回的订单号。 |
| cporder |
CP订单号 |
string |
游戏客户端在提交订单时传送的内部订单号。如果该渠道未接收该参数，则该字段为空字符串。 |
| info |
订单附加信息 |
string |
游戏客户端在提交订单时传送的附加信息。如果该渠道未接收该参数，则该字段为空字符串。 |
| sign |
签名参数 |
string |
MD5(签名内容 + ”|” + apiKey) 签名内容： code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info |
7.返回内容（JSON格式）：
| 字段名称 |
字段说明 |
类型 |
备注 |
| code |
响应码 |
int |
本次请求结果标志 |
| msg |
响应信息 |
string |
如果请求出错，描述错误信息。 |
| id |
用户唯一标识 |
string |
对应渠道的用户ID。 |
| order |
渠道订单号 |
string |
渠道返回的订单号。 |
| cporder |
CP订单号 |
string |
游戏客户端在提交订单时传送的内部订单号。如果该渠道未接收该参数，则该字段为空字符串。 |
| amount |
订单金额 |
string |
该笔订单价值折算为人民币的金额（以分为单位）。 |
| createtime |
订单创建时间 |
string |
该笔订单创建时间。 |
| Itemid |
道具id |
string |
该笔订单的道具id，如果没有传空字符串。 (该字段标识订单中的商品ID，需要与客户端下订单时对应的字段匹配，验证对比不符时不发货) |
| Itemquantity |
道具数量 |
Int |
该笔订单道具数量，没有传0。 （该字段标识客户端提交的订单中的道具数量，渠道不接受该字段时，客户端提交的订单没有该字段，此时直接传0或1均可） |
| status |
订单状态 |
int |
订单状态码。 |
| info |
其他信息 |
string |
备用字段，传送其他可供比对的信息。 |
响应码说明：
0：正常返回，结果成功
1：正常返回，结果失败
-99：未知错误
8.推荐处理方式
游戏服务端收到该请求后优先以CP订单号为条件查询，查询不到或请求中没有CP订单号时以渠道订单号为条件查询，找到匹配的订单信息并同步返回SDK服务端。
1.5 约定
l 支付相关接口内部订单号字段长度不能超过10位，格式使用英文字母和数字的组合，需要能够区分区服。不可重复。
l 渠道返回的用户id用于用户唯一标识。单区服内不可重复。
l 支付接口返回的amount是当次支付产生的实际金额。
该项目已开源，大家有兴趣可以自己研究或使用接入
项目地址：https://code.csdn.net/typesdk_code
项目地址：https://github.com/typesdk