跳到主要内容

内购

鉴权方式

本章节内容使用的鉴权方式为 签名鉴权 ，请确认这是您想要的鉴权方式，详见选择鉴权方式。

一、后端对接​

请完成后端内购的支付成功回调，在后端实现对应接口后，再执行下一步操作。

未实现后端接口就进行页面对接，可能会触发平台服务器的告警。

二、前端对接​

导入 SDK

请先确保已经导入 SDK，再执行下一步操作。

SDK 方法名称​

superPay

调用示例​

XL_GAME.callApp(
  'superPay',
  {
    cpOrderId: '123456',
    gameId: '2222',
    productName: '元宝',
    price: 100,
    server_id: '123',
    role_id: '456',
    // 由于 role_name（角色名称）需要作为 URL 参数传输，而游戏的角色名称可能存在特殊字符（这与游戏对角色名称的规范有关），
    // 故需对该参数值进行 URL 编码，在 JavaScript 中就是调用 encodeURIComponent
    // 在本示例，编码后的值为 %E6%88%91%E6%98%AF%E8%A7%92%E8%89%B2%E5%90%8D%E7%A7%B0
    role_name: encodeURIComponent('我是角色名称');
    sign: 'a11495d293065e07bc128182d00f1978',
    // 下面是游戏方传入的自定义字段，会透传到后端回调
    // 仅供示意，这些字段不是必需的，不参与签名
    cp_custom_key1: '我是游戏方提供的自定义字段，会透传到后端回调，这个字段不是必需的，不参与签名',
    cp_custom_key2: 123456789
    ...
  },
  (res) => console.log(res),
);

调用参数说明​

参数类型必选说明
cpOrderIdstring是游戏方的订单号
gameIdstring是平台的游戏 ID
productNamestring是商品名称
pricenumber是商品价格，单位“分”
server_idstring是区服 ID
role_idstring是角色 ID
role_namestring是角色名称，由于角色名称可能存在特殊字符，此值需经过 UTF-8 编码转义，比如 JavaScript 语言的 encodeURIComponent，C# 语言的 WebUtility.UrlEncode
signstring是通过 MD5 签名算法对上述参数进行签名获得的 32 位小写字符串，供平台方校验参数是否被篡改，具体计算方式见下方签名章节
其它字段string / number否其它自定义字段，回调游戏方接口时数据会写到 ext2 参数里面，参数不宜过多过长，数据不宜为嵌套的 JSON 格式（由于平台侧下单时会二次 encode，使用复杂的 JSON 数据可能会导致游戏方发货失败）

回调返回参数说明​

支付回调的返回参数是一个对象，各参数语义说明如下：

参数说明
errorCode错误码。errorCode = 0 为支付成功，其它均为失败
errorMsg错误信息
payment支付方式，可选值：alipay weixin
orderId订单 ID

签名（sign）​

调用本页的 SDK 方法时，存在签名参数 sign，该参数值的计算方式如下所示。

1. 签名规则​

  • 必传参数都参与签名。
  • 值为空字符串的字段不参与签名。
  • 将参与签名的参数按属性名升序排序，然后拼接为 k1=v1&k2=v2 格式（类似于浏览器的 URLSearchParams 但不需要对字符进行转义 ）
  • 将游戏的签名密钥 sign_key 拼接到上面 k1=v1&k2=v2 字符串的末尾，得到 k1=v1&k2=v2sign_key。
  • 对上面得到的字符串 k1=v1&k2=v2sign_key 进行 MD5 计算，得到 32 位小写字符串，即 MD5(k1=v1&k2=v2sign_key)。

2. 签名计算示例​

假设签名密钥 sign_key 为 test_key_e3654407c996bd0f8a45a14，必传的参数如下：

const params = {
  cpOrderId: "123456",
  gameId: "2222",
  productName: "元宝",
  price: 100,
  server_id: "123",
  role_id: "456",
  // role_name 参数值需要经过 URL 编码，参考本页面上面的“调用示例”章节的说明
  role_name: encodeURIComponent("我是角色名称"),
};

将必传参数按属性名升序排序，然后拼接为 k1=v1&k2=v2 格式：

const signString =
  "cpOrderId=123456&gameId=2222&price=100&productName=元宝&role_id=456&role_name=%E6%88%91%E6%98%AF%E8%A7%92%E8%89%B2%E5%90%8D%E7%A7%B0&server_id=123";

将签名密钥 sign_key 拼接字符串的末尾：

const signStringWithKey =
  "cpOrderId=123456&gameId=2222&price=100&productName=元宝&role_id=456&role_name=%E6%88%91%E6%98%AF%E8%A7%92%E8%89%B2%E5%90%8D%E7%A7%B0&server_id=123test_key_e3654407c996bd0f8a45a14";

MD5 计算字符串，得到签名（32 位小写字符串）：

const sign = MD5(signStringWithKey) = "bc42284e305f42b5f7e44ed433ed2de8";