文档中心
Return to top
支付服务端接入
编辑

支付服务端接入 ​

支付流程说明 ​

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平台订单创建时间（时间戳【毫秒】）时区：北京时区（东八区）