支付介面自定義參數 - 幫助中心

本文件詳細介紹軟代系統支付介面的自定義參數配置，幫助您實現個性化的支付體驗。透過這些參數，您可以自定義支付語言、支付方式、優惠碼自動應用等功能，並可透過 JS API 查詢商品價格資訊。

快速開始

在您的網站中嵌入軟代支付系統只需兩步：

1. 引入 JS 程式碼

在頁面的 <head> 或 <body> 結束前新增以下程式碼：先引入腳本，再初始化商戶資訊。

HTML

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

<!-- 第 2 步：初始化商戶資訊 -->
<script>
window.APSDAI({ hk_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: "hk",                    // 預設使用國際站
    language: "zh-tw",                  // 預設繁體中文
    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({
    hk_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-tw">
    中文支付
</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: 'hk'                // 預設使用國際站
});
</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-TW">
<head>
    <meta charset="UTF-8">
    <title>我的軟體商店</title>
</head>
<body>
    <h1>專業版軟體</h1>
    <p>價格：HK$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({
        hk_name: 'your_merchant_code',
        language: 'zh-tw',
        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

返回幫助中心