1 概要
通常，游戲開發商並不會只在一個渠道上線他們的游戲，接入越多的渠道，代表着可能獲取越多的用戶，但同時也代表着越多的接入SDK工作量、工期和費用。一款游戲要有足夠的用戶，甚至需要接入30家以上的各種渠道，以保障自己的市場覆蓋率。
單個SDK接入流程在一位有經驗的全職客戶端程序、一位全職服務端程序員、一位全職QA處理的情況下，需要3天時間才能完成。因此當一款產品面對30個甚至更多不同需求的渠道SDK時，人員成本和時間成本就會急劇增加。所以我們需要一個通用接口，來處理各種渠道的需求，這就是統一渠道SDK接入框架。
本部分主要提供平台SDK服務器與CP方游戲服務器交互的接口規范
1.2 支付基本流程
1.2.1 渠道支付流程
游戲客戶端在每次用戶點擊購買時向服務端請求生成內部訂單。並需要采用特定機制（例如一定時間內禁止連續點擊購買）防止用戶頻繁操作對服務器造成過高負載。
游戲服務端生成的所有內部訂單需要存儲待查。並在得到渠道返回的外部訂單后異步處理發貨操作並以特定機制通知客戶端更新數據顯示。
渠道支付接口負責完成貨幣交易操作，生成並存儲外部訂單，供對賬查詢使用。
SDK服務端轉發請求時額外存儲一份訂單日志數據，存儲內部訂單號，外部訂單號及訂單狀態，供對賬及查找BUG時作為參考。
1.2.2 一般渠道支付流程圖
1.3 協議說明
1.3.1 通信協議
SDK服務器采用HTTP協議作為通信協議，游戲服務器通過構造HTTP請求（POST方式）向SDK服務器發起接口請求。
1.3.2 數據協議
1.數據格式
請求消息和響應消息的內容都使用JSON表示數據。
2.字符編碼
請求與相應內容均采用UTF-8字符編碼
3.簽名規則
請求和響應中的簽名均使用md5哈希進行，算法如下：
MD5(簽名內容 + ”|” + apiKey)
說明：
·MD5使用RFC1321標准，編碼后需轉換成全小寫。
·描述簽名的表達式中，”+”表示做字符串連接，實際產生的待簽名字符串中並不存在。
·簽名內容指各接口請求數據中若干字段的拼接。基本格式為各字段值以 ”|” 符號分隔后直接連接。注意，由於”|”符號用作分隔字段，簽名內容中需避免出現該符號，換行符(回車或換行)等特殊符號也需要預先剔除。如果對應字段為空，仍然需要保留“|”符號占位。
·計算MD5簽名時，應以UTF8編碼取字符串的字節值。
·appid及apiKey由打包工具分配，打包工具使用方法請參考使用文檔。
4.簽名示例
假設請求數據為：
“data:{
“id” : 123,
“name” : “test”
“value” : “something”
“other” : “blarblar”
}
要求的簽名內容為:
id + name + value
則拼接后得出要簽名的內容串為
123|test|something
假定apiKey=aabbcc，則需要進行MD5哈希的字符串為：
123|test|something|aabbcc
1.4 接口說明
1.4.1 用戶會話驗證
1.請求地址：http://TypeSDK:PORT/{appid}/{channelid}/Login/
說明：URL中的{appid}代表游戲代碼，由打包工具生成，{channelid}代表渠道代碼，渠道代碼列表可以參考打包工具說明，可以從客戶端提交的參數中獲取當前渠道代碼。
例： http://192.168.0.1:40000/1000/1/Login/
2.調用方式：HTTP POST
3.接口描述：
驗證用戶登錄結果。
A) 游戲客戶端通過SDK客戶端的登錄動作獲取用戶登錄信息。
B) 游戲客戶端將獲取的用戶登錄信息傳送至游戲服務端。
C) 游戲服務端通過本請求將用戶登錄信息傳送到SDK服務端，驗證該登錄信息是否有效。
D) SDK服務端返回驗證結果及其他信息，供游戲服務器使用。
4.請求方：游戲服務端
5.響應方：SDK服務端
6.請求內容（JSON格式）：
| 字段名稱 |
字段說明 |
類型 |
備注 |
| id |
用戶唯一標識 |
string |
對應渠道的用戶ID。並非必傳，未作說明的情況下傳空字符串。 |
| token |
用戶登錄會話標識 |
string |
本次登錄標識。並非必傳，未作說明的情況下傳空字符串。 |
| data |
附加信息 |
JSON |
附加信息。並非必傳，根據渠道不同，該字段含義不同，未作說明的情況下傳空字符串。 |
| sign |
簽名參數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容： Id + ”|” + token + ”|” + data |
7.返回內容（JSON格式）：
| 字段名稱 |
字段說明 |
類型 |
備注 |
| code |
響應碼 |
int |
本次請求結果標志 |
| id |
用戶唯一標識 |
string |
對應渠道的用戶ID |
| nick |
用戶在渠道的昵稱 |
string |
對應渠道的用戶昵稱 |
| token |
用戶登錄會話標識 |
string |
本次登錄標識 |
| msg |
響應信息 |
string |
如果請求出錯，描述錯誤信息。 |
| value |
渠道返回信息 |
JSON |
渠道返回的原始結果信息。 |
響應碼說明：
0：渠道正常返回，結果成功
1：渠道正常返回，結果失敗
2：渠道服務端請求錯誤
-1：提交的請求參數錯誤
-2：提交的請求轉換成渠道參數錯誤
-3：提交的請求參數簽名錯誤
-99：未知錯誤
id,nick,token說明：
根據不同渠道定義的返回字段不同，此三個字段不一定有值。渠道未返回對應字段時，該字段值為空字符串。
1.4.2 充值結果回調
1.請求地址：
該地址為充值結果通知地址，由游戲服務端在下文的SaveOrder接口中通過notifyurl字段提交至SDK服務端。
2.調用方式：HTTP POST
3.接口描述：
通知用戶充值結果。
A) 用戶在游戲中向SDK客戶端提交充值請求。
B) SDK客戶端將充值請求轉發渠道方
C) 渠道方異步執行充值。
D) 渠道方將充值結果發送給SDK服務端
E) SDK服務端通過該接口將充值結果發送給游戲服務端。
F) 游戲服務端處理充值邏輯。
G) 游戲服務端向SDK服務端返回處理結果。
H) SDK服務端向渠道方返回處理結果。
4.請求方：SDK服務端
5.響應方：游戲服務端
6.請求內容（JSON格式）：
| 字段名稱 |
字段說明 |
類型 |
備注 |
| code |
響應碼 |
int |
渠道返回的充值結果。 |
| id |
用戶唯一標識 |
string |
對應渠道的用戶ID。 |
| order |
渠道訂單號 |
string |
渠道返回的訂單號。 |
| cporder |
CP訂單號 |
string |
游戲客戶端在提交訂單時傳送的內部訂單號。如果該渠道未接收該參數，則該字段為空字符串。 |
| info |
訂單附加信息 |
string |
游戲客戶端在提交訂單時傳送的附加信息。如果該渠道未接收該參數，則該字段為空字符串。 |
| sign |
簽名參數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容： code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info |
| amount |
訂單金額 |
string |
該筆訂單價值折算為人民幣的金額（以分為單位）供服務端校驗使用，不參與簽名。 |
7.返回內容（JSON格式）：
| 字段名稱 |
字段說明 |
類型 |
備注 |
| code |
響應碼 |
int |
本次請求結果標志 |
| msg |
響應信息 |
string |
如果請求出錯，描述錯誤信息。 |
響應碼說明：
0：正常返回，結果成功
1：正常返回，結果失敗
-99：未知錯誤
8.推薦處理方式
游戲服務端收到該請求后可保存該次請求參數，隨即返回code=0，表明成功收到消息。之后異步處理充值或發放道具邏輯。
1.4.3 充值信息提交
1.請求地址：http://TypeSDK:PORT/{appid}/{channelid}/SaveOrder/
說明：URL中的{appid}代表游戲代碼，由打包工具生成，{channelid}代表渠道代碼，渠道代碼列表可以參考打包工具文檔，可以從客戶端提交的參數中獲取當前渠道代碼。
例： http://192.168.0.1:40000/1000/1/SaveOrder/
2.調用方式：HTTP POST
3.接口描述：
充值信息存檔待查。
A) 用戶在游戲中向游戲服務端提交充值請求。
B) 游戲服務端生成內部充值訂單號及相關充值信息
C) 游戲服務端將內部充值訂單號及相關充值信息返回游戲客戶端，供其提交給渠道方。
D) 游戲服務端異步將內部充值訂單號，該筆訂單回調url及相關充值信息發送給SDK服務端。
E) SDK服務端將充值信息存檔待查並返回處理結果。
4.請求方：游戲服務端
5.響應方：SDK服務端
6.請求內容（JSON格式）：
| 字段名稱 |
字段說明 |
類型 |
備注 |
| cporder |
CP訂單號 |
string |
游戲客戶端在提交訂單時傳送的內部訂單號。 |
| data |
訂單信息 |
string |
由CP生成訂單時自定義的附加信息,不能為空及空字符串。 |
| sign |
簽名參數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容： cporder + ”|” + data |
| notifyurl |
訂單回調url |
string |
該筆訂單回調通知游戲服務端的url，不參與簽名。 |
| verifyurl |
訂單查詢url |
string |
該筆訂單向游戲服務端查詢詳情的url，不參與簽名。 |
7.返回內容（JSON格式）：
| 字段名稱 |
字段說明 |
類型 |
備注 |
| code |
響應碼 |
int |
本次請求結果標志 |
| msg |
響應信息 |
string |
如果請求出錯，描述錯誤信息。 |
響應碼說明：
0：正常返回，存檔成功
1：正常返回，存檔失敗
-1：系統錯誤
-2：參數錯誤
-3：簽名校驗錯誤
-99：未知錯誤
注意：SaveOrder接口在服務端生成內部訂單號時請求。只有獲取到該請求成功返回，才能允許客戶端作后續充值動作。
1.4.4 充值信息確認
1.請求地址：http://TypeSDK:PORT/{appid}/{channelid}/CheckOrder/
說明：URL中的{appid}代表游戲代碼，由打包工具生成，{channelid}代表渠道代碼，渠道代碼列表可以參考打包工具文檔，可以從客戶端提交的參數中獲取當前渠道代碼。
例： http://192.168.0.1:40000/1000/1/CheckOrder/
2.調用方式：HTTP POST
3.接口描述：
充值信息查詢。
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