支付接口自定義參數 - 幫助中心

本文檔詳細介紹軟代系統支付接口嘅自定義參數配置，幫你實現個性化嘅支付體驗。通過這些參數，你可以自定義支付語言、支付方式、優惠碼自動應用等功能，並可以通過 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`（香港站/國際站）
`data-apsdai-currency`	打開支付窗口默認支付幣種	`cny`（人民幣）、`usd`（美元）、`twd`（新台幣）、`hkd`（港幣）

使用示例

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>

<!-- 默認美元支付 -->
<h2 data-apsdai-checkout="test" data-apsdai-currency="usd">默認美元支付</h2>

多站點配置

如果你同時使用中國站和國際站，可以配置多站點支援：

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>價格：￥</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

返回幫助中心