Skip to content
支付服务端接入

支付服务端接入

支付流程说明

CP对接233平台交易时序图【重客户端】

在233平台游戏道具充值购买场景

  1. 涉及对接方:游戏开发商(CP)、233游戏平台、第三方支付平台(微信支付、支付宝等);
  2. 涉及业务对接节点: 游戏开发商游戏程序、233平台交易SDK、游戏开发商服务器端、233服务器端、第三方支付平台;
  3. CP在233平台下单的订单号必须要保证在CP交易系统中唯一性(与其他CP无关),如果重复,会对后续订单查询等接口造成不可逆影响,平台与CP也无法根据订单明细进行对账;
  4. 233平台在新版本发货(V2)版本接口中新增了平台唯一性订单交易编号(tradeNo),推荐CP对接发货功能对接到V2的流程中;平台的tradeNo是具备唯一性;
  5. CP在确认收到发货接口回调时(流程图第8步)建议回查233平台订单交易状态(接入参考文档)
  6. CP需要自己保证发货接口的幂等性,233平台不保证同一笔订单发货接口只调用1次,且可能存在并发回调;
  7. CP推荐在确认发货成功后再给出约定的已发货响应值,如果处理是失败,233平台还会重试多次发货回调;
  8. CP接收回调后,推荐根据tradeNo查询233平台交易结果,并判断 订单原值金额 = CP本地订单金额;
  • 如金额不一致,可认为是受到攻击;
  • 如CP仍然发货,233平台与CP结算将以实际订单收款数据做结算,产生损失将由CP自行承担;
  • 优惠券抵扣金额推荐不做是否发货逻辑判断,可用作财务结算对账使用;

发货通知接口

接口说明:

发货通知接口即支付结果通知接口,当玩家游戏内充值成功后,平台游戏服务端向开发者平台CP配置的回调地址发送订单通知,CP需要根据按照以下规则进行验签,以及返回平台要求的返回值。

注意

因为网络或其他原因,可能会出现重复通知的情况,CP需要做好去重处理,避免重复发货

回调验签规则

平台目前采用的是SHA1方式对参数加密验签, 以下使用的secret为开放平台分配的AppSecret 签名规则如下:

参数大小写敏感(区分大小写); 多参数拼接采用 & 符号作为分隔符; 参数的value为null或者是空字符串【""】是不参与签名,签名的参数(sign)也不参与签名; 参数签名顺序是按照参数名的ASCII码从小到大排序; 所有业务参数顺序拼接完成后,再在最后拼接cp秘钥参数,参数名为:secret; 签名值: 在原有参数列表中增加签名参数 sign ,与普通参数平级;

签名示例:

参数原始数据有:

java
{
    "orderId" : "202001101301002" , 
    "productName" : "pizza" , 
    "year" : 2020 ,  
    "desc" : "" , 
    "sort" :  107
}
{
    "orderId" : "202001101301002" , 
    "productName" : "pizza" , 
    "year" : 2020 ,  
    "desc" : "" , 
    "sort" :  107
}

CP在233平台秘钥为: 4D2CD76B80C40B3B4EAE2E04BACA46B8

签名字符串为:
orderId=202001101301002&productName=pizza&sort=107&year=2020&secret=4D2CD76B80C40B3B4EAE2E04BACA46B8

签名值(SIGN):9AD9B18B1E0E59287AB8E5E3E414D072

该值为SHA1加密后截取后32位并转大写

在参数体内再额外增加签名的值,提交的参数即为

json
{
    "orderId" : "202001101301002" , 
    "productName" : "pizza" , 
    "year" : 2020 ,  
    "desc" : "" , 
    "sort" :  107, 
    "sign" : "9AD9B18B1E0E59287AB8E5E3E414D072" 
}
{
    "orderId" : "202001101301002" , 
    "productName" : "pizza" , 
    "year" : 2020 ,  
    "desc" : "" , 
    "sort" :  107, 
    "sign" : "9AD9B18B1E0E59287AB8E5E3E414D072" 
}

V2版本接入

接口说明: 充值回调接口,默认都走V2版本,V1接口逐步废弃

接收方: 由CP在233开发者平台配置发货地址 和 选择接入版本【V2】

请求方式: POST

Content-Type: APPLICATION/JSON

接口安全类型: SHA1接口参数验签

请求参数

json
{
"tradeNo"           :   String,
"cpOrderId"         :   String,
"productCode"       :   String,
"productName"       :   String,
"productPrice"      :   unsigned int,
"count"             :   unsigned int,
"nonce"             :   String,
"amount"            :   unsigned int,
"couponDeductAmount":   unsigned int,
"extra"             :   String,
"sign"              :   String
}
{
"tradeNo"           :   String,
"cpOrderId"         :   String,
"productCode"       :   String,
"productName"       :   String,
"productPrice"      :   unsigned int,
"count"             :   unsigned int,
"nonce"             :   String,
"amount"            :   unsigned int,
"couponDeductAmount":   unsigned int,
"extra"             :   String,
"sign"              :   String
}

参数说明:

字段是否为空描述
tradeNoN233平台对应的交易订单编号(具备唯一性)
cpOrderIdN供应商交易订单id(由供应商下单后出传入)
productCodeN商品编号(供应商下单时提供)
productNameN商品名称(供应商下单时提供)
productPriceN商品单价(单位:分【人民币分】)
countN订单购买购买数量
nonceN随机安全码(无业务意义,增加接口安全随机性)
amountN订单原值金额(单位:分【人民币】),建议服务端做一下金额校验,避免被刷
couponDeductAmountY优惠券抵扣金额(因优惠券而优惠的金额)(单位:分【人民币】),当该笔交易未使用优惠券时,值为0
extraY由供应商预下单时传入扩展透传参数,原封不动给到供应商系统,当CP交易系统下单未提供扩展字段时,该字段为空
signN签名字段,签名规则

游戏方响应结果

游戏方需要按照以下格式返回结果给平台,平台会根据对应的code做不同的处理。

重要提示

服务端接收回调请求后,请务必校验金额,确保收到的金额与实际物品金额一致,防止游戏金额被篡改导致损失或数据异常,确保游戏资产安全。

json
{
"code"      :   int, //响应状态码
"message"   :   String  //状态码描述信息
}
{
"code"      :   int, //响应状态码
"message"   :   String  //状态码描述信息
}

**code响应码说明: **

状态码描述是否重试请求
200业务处理成功,发货成功
22100数据签名不正确
22101接口参数验证不通过
22103未知业务错误(CP运行时未知错误异常)
22102CP无法发货(例如因为无库存、商品下架等原因,明确指出该笔订单无法履约【233平台会立刻给用户退款,并取消该笔订单】);否(平台退款给玩家)

PS: 当游戏服务端返回非200给平台,平台会按照斐波那契的数列间隔向游戏服务重试请求

订单查询接口

CP根据订单号从233平台服务器查询指定订单的情况

前置说明

CP对接233开放平台接口有一套标准接口协议【只对接B端CP的服务器端功能接口】, 涉及CP的游戏身份认证和接口功能认证,统一接口鉴权请阅读 开放平台鉴权接入指南

V2版本

接口地址: https://openapi.metaapp.cn/v2/trade/order/query

请求方式: POST

入参约束: Content-Type: APPLICATION/JSON

Header信息: 查看header参数规则

请求参数

json
{
"tradeNo": "233平台订单号,建议使用该字段",
"cpOrderId" :"游戏方自定义订单号"
}
{
"tradeNo": "233平台订单号,建议使用该字段",
"cpOrderId" :"游戏方自定义订单号"
}

参数说明:

字段是否为空描述
tradeNoY233平台对应的交易订单编号(具备唯一性)
cpOrderIdY供应商交易订单id(由供应商下单后出传入)【不推荐使用,只是对老系统兼容,当CP无法保证其cpOrderId在CP交易系统中的唯一性时,会出现查询的交易数据非预期的目标数据】

注意

两个参数不能同时为空或空字符串!必须有一个有值,如果同时传入,优先使用tradeNo【不会再使用cpOrderId,就算对应的tradeNo的订单数据不存在,也不会使用cpOrderId尝试获取数据】

重要提示

订单查询成功后,请务必校验金额,确保支付的金额与实际物品金额一致,防止游戏金额被篡改导致损失或数据异常,确保游戏资产安全。

响应数据:

json
{
"code" : int, // 接口状态码,200:正常,其它均为异常; 1016:标识订单数据不存在;
"message" : String, //  接口响应状态描述或异常原因;
"data" : {
           "cpOrderId"         :       String, 
            "tradeNo"           :       String,
            "productCode"       :       String,
            "productName"       :       String,
            "productPrice"      :       unsigned int,
            "count"             :       unsigned int,
            "payed              :       bool,
            "amount"            :       unsigned int,
            "couponDeductAmount":       unsigned int,
            "extra"             :       String,
            "createTime"        :       long
          }
}
{
"code" : int, // 接口状态码,200:正常,其它均为异常; 1016:标识订单数据不存在;
"message" : String, //  接口响应状态描述或异常原因;
"data" : {
           "cpOrderId"         :       String, 
            "tradeNo"           :       String,
            "productCode"       :       String,
            "productName"       :       String,
            "productPrice"      :       unsigned int,
            "count"             :       unsigned int,
            "payed              :       bool,
            "amount"            :       unsigned int,
            "couponDeductAmount":       unsigned int,
            "extra"             :       String,
            "createTime"        :       long
          }
}

data字段说明:

字段是否为空描述
cpOrderIdN供应商交易订单id(由供应商下单后出传入)
tradeNoN233平台对应的交易订单编号(具备唯一性)
productCodeN商品编号(供应商下单时提供)
productNameN商品名称(供应商下单时提供)
productPriceN商品单价(单位:分【人民币分】)
countN订单购买购买数量
payedN该笔交易是否已经付款
amountN订单原值金额(单位:分【人民币】)
couponDeductAmountY优惠券抵扣金额(单位:分【人民币】),当该笔交易未使用优惠券时,该字段为空
extraY由供应商预下单时传入扩展透传参数,原封不动给到供应商系统,当CP交易系统下单未提供扩展字段时,该字段为空
createTimeN233平台订单创建时间(时间戳【毫秒】)时区:北京时区(东八区)