支付接口自定义参数 - 帮助中心

本文档详细介绍软代系统支付接口的自定义参数配置，帮助您实现个性化的支付体验。通过这些参数，您可以自定义支付语言、支付方式、优惠码自动应用等功能，并可通过 JS API 查询商品价格信息。

快速开始

在您的网站中嵌入软代支付系统只需两步：

1. 引入 JS 代码

在页面的 <head> 或 <body> 结束前添加以下代码：先引入脚本，再初始化商户信息。

HTML

<!-- 第 1 步：引入软代 JS -->
<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>

<!-- 第 2 步：初始化商户信息 -->
<script>
window.APSDAI({ name: 'your_merchant_code' });  // 替换为您的商户唯一编码
</script>

2. 添加支付按钮

在需要触发支付的元素上添加 data-apsdai-checkout 属性：

HTML

<button data-apsdai-checkout="your_product_path">立即购买</button>

获取商户编码

登录软代商户后台，进入「设置」→「配置」→「查看示例」即可复制您的专属 JS 代码。

两种初始化方式

软代 JS 支持两种初始化写法，功能一致，请二选一，不要混用：

方式	写法	说明
方式一：实例化（推荐）	引入脚本后调用 `window.APSDAI({ ... })`	写法直观，且可拿到实例调用 JS API（如查询商品价格）
方式二：声明式（旧版兼容）	引入脚本前声明 `window.Apsdai` 配置对象	旧版写法，已接入的站点无需改动，可继续使用

方式一：实例化（推荐）

脚本引入后调用 window.APSDAI() 并传入配置。如需调用 JS API，请用变量保存返回的实例：

HTML

<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>
<script>
// 仅初始化
window.APSDAI({ name: 'your_merchant_code' });

// 需要调用 JS API 时，保存实例
const example = window.APSDAI({ name: 'your_merchant_code' });
</script>

方式二：声明式（旧版兼容）

在引入脚本之前声明配置对象，脚本加载后会自动读取：

HTML

<script>
window.Apsdai = Object.assign(window.Apsdai || {}, {
    name: 'your_merchant_code'  // 替换为您的商户唯一编码
});
</script>
<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>

切勿混用两种写法

使用 window.APSDAI({ ... }) 实例化时，禁止再通过 window.Apsdai 传入配置参数，配置只能在实例化参数中传递，否则会造成配置冲突。

全局配置参数

下列参数既可作为 window.APSDAI({ ... }) 的实例化参数传入，也可在旧版声明式写法中通过 window.Apsdai 配置：

参数	类型	必填	说明
`name`	String	是*	中国站商户唯一编码（中国站必填）
`hk_name`	String	是*	香港站/国际站商户唯一编码（国际站必填）
`host_site`	String	否	默认站点，可选 `cn`（中国站）或 `hk`（香港站）。默认为 `cn`
`language`	String	否	界面语言，可选 `zh-cn`（简体中文）、`zh-tw`（繁体中文）、`en`（英文）。默认根据浏览器语言自动设置
`open_type`	String	否	打开窗口类型，可选 `pay`（支付）或 `cart`（购物车）。默认为 `pay`

JavaScript

<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>
<script>
window.APSDAI({
    name: "your_cn_merchant_code",      // 中国站商户编码
    hk_name: "your_hk_merchant_code",   // 国际站商户编码
    host_site: "cn",                    // 默认使用中国站
    language: "zh-cn",                  // 默认简体中文
    open_type: "pay"                    // 默认打开支付窗口
});
</script>

工单系统配置

软代系统内置工单功能，可以在页面右下角显示工单入口，方便用户提交问题。通过 work_order 对象进行配置：

参数	类型	说明
`open`	Number	`1` 显示工单入口，`2` 隐藏（可通过 API 打开）
`theme_color`	String	主题颜色，如 `#16B8F3`
`icon`	String	角标图片 URL
`icon_width`	String	角标宽度（像素）
`icon_height`	String	角标高度（像素）
`icon_right`	String	角标距离窗口右边距离（像素）
`icon_bottom`	String	角标距离窗口底部距离（像素）
`header`	String	工单窗口头部文字
`title`	String	工单窗口标题
`description`	String	工单窗口说明文字
`copyright`	String	版权信息
`collect_info`	Array	需要收集的额外信息字段

JavaScript

<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>
<script>
window.APSDAI({
    name: "your_merchant_code",
    work_order: {
        open: 1,                          // 显示工单入口
        theme_color: "#16B8F3",           // 主题颜色
        icon: "https://example.com/icon.png",
        icon_width: "55",
        icon_height: "55",
        icon_right: "40",
        icon_bottom: "40",
        header: "客服支持",
        title: "提交工单",
        description: "⚡️ 我们将尽快为您解决问题！",
        copyright: "Powered by APSDAI",
        collect_info: [
            { name: "手机号" },
            { name: "订单号" }
        ]
    }
});
</script>

手动打开工单

当 open 设置为 2 时，可以通过调用 ApsdaiInstance().openTickets() 方法手动打开工单窗口。

HTML 属性参数

除了全局配置，您还可以在 HTML 元素上使用 data-* 属性来配置单个支付按钮的行为：

属性	说明	可选值
`data-apsdai-checkout`	商品 PATH（必填）	商品的唯一标识路径
`data-apsdai-language`	指定支付界面语言	`zh-cn`（简体）、`zh-tw`（繁体）、`en`（英文）
`data-apsdai-pay`	指定支付方式	`weChat` - 微信支付 `pWeChat` - 服务商微信支付 `alipay` - 支付宝 `pAlipay` - 服务商支付宝 `paypal` - PayPal `stripe` - 信用卡 `shouMoneyBaUnionPay` - 云闪付
`data-apsdai-coupon`	自动应用优惠码	优惠码字符串
`data-apsdai-open-type`	打开窗口类型	`pay`（支付）、`cart`（购物车）
`data-apsdai-site`	指定支付站点	`cn`（中国站）、`hk`（香港站/国际站）

使用示例

HTML

<!-- 基础支付按钮 -->
<button data-apsdai-checkout="product_path">立即购买</button>

<!-- 指定简体中文界面 -->
<button data-apsdai-checkout="product_path" data-apsdai-language="zh-cn">
    中文支付
</button>

<!-- 指定支付宝支付 -->
<button data-apsdai-checkout="product_path" data-apsdai-pay="alipay">
    支付宝付款
</button>

<!-- 自动应用优惠码 -->
<button data-apsdai-checkout="product_path" data-apsdai-coupon="SAVE20">
    使用优惠码购买
</button>

<!-- 打开购物车 -->
<button data-apsdai-checkout="product_path" data-apsdai-open-type="cart">
    加入购物车
</button>

<!-- 国际站支付 -->
<button data-apsdai-checkout="product_path" data-apsdai-site="hk">
    International Payment
</button>

多站点配置

如果您同时使用中国站和国际站，可以配置多站点支持：

HTML

<!-- 配置双站点 -->
<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>
<script>
window.APSDAI({
    name: 'cn_merchant_code',      // 中国站编码
    hk_name: 'hk_merchant_code',   // 国际站编码
    host_site: 'cn'                // 默认使用中国站
});
</script>

<!-- 中国站支付按钮 -->
<button data-apsdai-checkout="product" data-apsdai-site="cn">
    国内支付
</button>

<!-- 国际站支付按钮 -->
<button data-apsdai-checkout="product" data-apsdai-site="hk">
    International Payment
</button>

注意

未指定 data-apsdai-site 属性时，将使用初始化时 host_site 参数指定的默认站点。

商品价格查询 API

通过实例的 Product.Prices() 方法，可以获取后台商品的标题、规格、简介、图片以及价格信息，便于在自己的页面上动态渲染商品卡片和促销价。

方法签名

JavaScript

instance.Product.Prices(path, currency?) => Promise

参数	类型	必填	说明
`path`	String \| Array	是	后台商品的 PATH 值，可传单个字符串或多个 PATH 组成的数组
`currency`	String	否	指定货币。国际站支持 `cny`、`usd`、`twd`、`hkd`；国内站仅支持 `cny`。不传则自动选择货币

调用示例

JavaScript

<script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>
<script>
// 注意：使用实例化方式时，禁止通过 window.Apsdai 传入配置参数
const example = window.APSDAI({ name: 'your_merchant_code' });

// 示例 1：使用自动货币选择（PATH1 为后台商品的 PATH 值）
example.Product.Prices('PATH1')
    .then(res => { console.log(res); })
    .catch(err => { console.log(err); });

// 示例 2：指定货币
example.Product.Prices('PATH1', 'usd');

// 示例 3：一次查询多个商品
example.Product.Prices(['PATH1', 'PATH2', 'PATH3'], 'cny');
</script>

响应示例

JSON

{
    "code": 0,
    "data": {
        "PATH1": {
            "title": "测试商品",
            "sku": "规格",
            "desc": "软件简介",
            "images": "url",
            "original_price": 12,
            "price": 2,
            "is_promotion": true
        },
        "PATH2": {
            "title": "测试商品",
            "sku": "规格",
            "desc": "软件简介",
            "images": "url",
            "original_price": 12,
            "price": 2,
            "is_promotion": true
        }
    },
    "msg": ""
}

字段	类型	说明
`code`	Number	`0` 表示成功，其他值表示失败，失败原因见 `msg`
`data`	Object	以商品 PATH 为键的商品信息集合
`data[path].title`	String	商品名称
`data[path].sku`	String	商品规格
`data[path].desc`	String	商品简介
`data[path].images`	String	商品图片地址
`data[path].original_price`	Number	商品原价
`data[path].price`	Number	当前实际售价（促销时为促销价）
`data[path].is_promotion`	Boolean	是否处于促销中
`msg`	String	提示信息，成功时为空字符串

使用建议

批量渲染商品列表时，建议一次传入 PATH 数组查询，避免多次请求；价格由后台统一维护，前端无需硬编码。

完整示例

以下是一个完整的集成示例，包含全局配置、工单系统和多种支付按钮：

HTML

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>我的软件商店</title>
</head>
<body>
    <h1>专业版软件</h1>
    <p>价格：¥99</p>
    
    <!-- 支付按钮 -->
    <button data-apsdai-checkout="pro-software">立即购买</button>
    
    <!-- 带优惠码的按钮 -->
    <button data-apsdai-checkout="pro-software" data-apsdai-coupon="WELCOME10">
        新用户优惠购买
    </button>

    <!-- 软代系统配置 -->
    <script src="https://i-cdn.softscdn.com/apsdai.min.js"></script>
    <script>
    window.APSDAI({
        name: 'your_merchant_code',
        language: 'zh-cn',
        work_order: {
            open: 1,
            theme_color: "#16B8F3",
            icon_width: "55",
            icon_height: "55",
            icon_right: "40",
            icon_bottom: "40",
            header: "客服",
            title: "需要帮助？",
            description: "我们随时为您服务！"
        }
    });
    </script>
</body>
</html>

URL 参数方式

您也可以通过 URL 哈希参数快速指定商品：

URL

# 在访问 URl 添加 #apsdai-xxx ( xxx 代码 path 值 )
https://www.yoursite.com#apsdai-xxx

返回帮助中心