沃特嚴選｜商戶 API 文件

正式商戶 API

以下只列公開商戶可串接的正式 API；查詢、餘額、銀行列表、回調重送與相容功能都已納入正式 API 說明。

金鑰與簽名規則

簽名步驟

1. 取所有要送出的參數，排除 sign。
2. 排除 null 與空字串 ''。
3. 若參數是物件或陣列，例如 extra，簽名時轉成 JSON 字串。
4. 參數名稱依 A-Z / ASCII 排序。
5. 組成 key=value&key2=value2。
6. 最後接上 &key=API_SECRET。
7. 做 MD5，並轉成大寫 32 碼。

function makeSign(array $params, string $secret): string
{
    unset($params['sign']);

    $data = [];
    foreach ($params as $key => $value) {
        if ($value === null || $value === '') continue;
        $data[$key] = is_array($value)
            ? json_encode($value, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
            : $value;
    }

    ksort($data, SORT_STRING);

    $pairs = [];
    foreach ($data as $key => $value) {
        $pairs[] = $key . '=' . $value;
    }

    return strtoupper(md5(implode('&', $pairs) . '&key=' . $secret));
}

const crypto = require('crypto');

function makeSign(params, secret) {
  const data = {};
  Object.keys(params).forEach((key) => {
    const value = params[key];
    if (key === 'sign') return;
    if (value === null || value === undefined || value === '') return;
    data[key] = typeof value === 'object' ? JSON.stringify(value) : String(value);
  });

  const base = Object.keys(data)
    .sort()
    .map((key) => `${key}=${data[key]}`)
    .join('&');

  return crypto.createHash('md5')
    .update(`${base}&key=${secret}`)
    .digest('hex')
    .toUpperCase();
}

1. 建立收單

用於商戶建立一筆代收 / 收單資料，資料會寫入收單列表，並可進入 APP 代理賣幣流程。

Request 欄位

狀態值

• pending：未付 / 待處理
• succeeded：已付 / 成功
• manual：後台補單 / 已補
• collection_status=pending：待匹配
• collection_status=matched：已匹配
• collection_status=exception：異常

{
    "uid": "ABCDE",
    "orderid": "COL202605200001",
    "merchant_order_no": "M-COL202605200001",
    "gateway_code": "gateway_c",
    "channel": "API",
    "currency": "TWD",
    "amount": 2500,
    "paid_amount": 0,
    "status": "pending",
    "collection_status": "pending",
    "collection_account_name": "測試收款戶",
    "collection_account_no": "80844397416179",
    "collection_bank_name": "中信銀行",
    "counterparty_account": "0040000256001018003",
    "member_bank_name": "台灣銀行",
    "user_id": "U1001",
    "user_name": "測試會員",
    "notify_url": "https://merchant.example.com/notify/collection",
    "return_url": "https://merchant.example.com/return",
    "timestamp": 1779214673,
    "sign": "2C4605785AD325985337770959CEFB42"
}

curl -X POST "https://api.wattt.asia/api/v1/merchant/collections" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uid":"ABCDE","orderid":"COL202605200001","merchant_order_no":"M-COL202605200001","gateway_code":"gateway_c","channel":"API","currency":"TWD","amount":2500,"paid_amount":0,"status":"pending","collection_status":"pending","collection_account_name":"測試收款戶","collection_account_no":"80844397416179","collection_bank_name":"中信銀行","counterparty_account":"0040000256001018003","member_bank_name":"台灣銀行","user_id":"U1001","user_name":"測試會員","notify_url":"https://merchant.example.com/notify/collection","return_url":"https://merchant.example.com/return","timestamp":1779214673,"sign":"2C4605785AD325985337770959CEFB42"}'

Response 成功範例

{
  "ok": 1,
  "message": "收單模擬資料已建立",
  "data": {
    "id": 123,
    "orderid": "COL202605200001",
    "merchant_order_no": "M-COL202605200001",
    "status": "pending",
    "amount": 2500,
    "paid_amount": 0,
    "payment_bank_account": "0040000256001018003",
    "counterparty_account": "0040000256001018003"
  }
}

2. 建立代付

用於商戶建立一筆代付資料，資料會寫入代付列表，並可進入 APP 代理買幣流程。

Request 欄位

狀態值

• pending：待處理
• processed：已處理 / 成功
• cancelled：已撤銷 / 失敗 / 駁回
• success、succeeded 會轉為 processed
• failed、rejected 會轉為 cancelled

{
    "uid": "ABCDE",
    "serial_no": "PO202605200001",
    "merchant_order_no": "M-PO202605200001",
    "channel": "代付",
    "amount": 3000,
    "actual_amount": 3000,
    "status": "pending",
    "payee_name": "王小明",
    "payee_bank": "中國信託",
    "payee_account": "822123456789012",
    "payment_tag": "PAYOUT-TEST",
    "beneficiary_name": "王小明",
    "notify_url": "https://merchant.example.com/notify/payout",
    "timestamp": 1779214673,
    "sign": "EE6E4F93675344E8ADE95266EEC1A2E9"
}

curl -X POST "https://api.wattt.asia/api/v1/merchant/payouts" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uid":"ABCDE","serial_no":"PO202605200001","merchant_order_no":"M-PO202605200001","channel":"代付","amount":3000,"actual_amount":3000,"status":"pending","payee_name":"王小明","payee_bank":"中國信託","payee_account":"822123456789012","payment_tag":"PAYOUT-TEST","beneficiary_name":"王小明","notify_url":"https://merchant.example.com/notify/payout","timestamp":1779214673,"sign":"EE6E4F93675344E8ADE95266EEC1A2E9"}'

Response 成功範例

{
  "ok": 1,
  "message": "代付模擬資料已建立",
  "data": {
    "id": 456,
    "serial_no": "PO202605200001",
    "merchant_order_no": "M-PO202605200001",
    "status": "pending",
    "amount": 3000
  }
}

3. 訂單查詢

收單與代付皆可用商戶單號或平台交易號查詢；回應同時提供目前系統欄位與 v6.0 常見欄位。

收單查詢

{
    "uid": "ABCDE",
    "orderid": "COL202605200001",
    "timestamp": 1779214673,
    "sign": "89A8629D66DD0F00578AF485E71FA3B0"
}

代付查詢

{
    "uid": "ABCDE",
    "serial_no": "PO202605200001",
    "timestamp": 1779214673,
    "sign": "F7BDCA65EC468E3CAEB8C0A03446F5AA"
}

Response 範例

{
  "ok": 1,
  "code": 0,
  "text": "success",
  "status": "PAID",
  "paid": 2500,
  "tradeNo": "123",
  "orderNo": "M-COL202605200001",
  "data": {
    "system_status": "succeeded",
    "amount": 2500,
    "paid_amount": 2500,
    "callback_status": "succeeded"
  }
}

4. 餘額查詢 / 銀行列表

商戶餘額查詢

{
    "uid": "ABCDE",
    "timestamp": 1779214673,
    "sign": "170F0B101AFD1C4BA4B45A7DEBCCDB01"
}

回傳欄位包含 balance、balance0、balance1、balance2，以及 data.summary 內的收單、代付、凍結與可用餘額明細。

銀行列表

https://api.wattt.asia/api/v1/merchant/banks?q=中國信託

回調重送

{
    "uid": "ABCDE",
    "type": "collection",
    "orderid": "COL202605200001",
    "timestamp": 1779214673,
    "sign": "29480AC603978CFC082D754DBE5A39B1"
}

5. 商品查詢

可帶 merchant_uid 過濾商戶商品與平台通用商品。

https://api.wattt.asia/api/v1/products?merchant_uid=ABCDE

Response 範例

{
  "ok": 1,
  "items": [
    {
      "id": "1",
      "uid": "PRODUCT_UID",
      "sku": "SKU001",
      "name": "商品名稱",
      "currency": "TWD",
      "price_hkd_cents": 100000
    }
  ]
}

6. 異步通知 / 回調

建單可帶 notify_url，代付也可帶 reverse_url。如需人工重送，可呼叫 POST /api/v1/merchant/callbacks/retry。商戶收到通知後請回應純文字 success。

建議代收回調格式

{
  "type": "collection",
  "uid": "ABCDE",
  "orderid": "COL202605200001",
  "merchant_order_no": "M-COL202605200001",
  "trade_no": "123",
  "amount": 2500,
  "paid_amount": 2500,
  "status": "succeeded",
  "paid_at": "2026-05-18 15:30:00",
  "timestamp": 1779214673,
  "sign": "MD5SIGN"
}

建議代付回調格式

{
  "type": "payout",
  "uid": "ABCDE",
  "serial_no": "PO202605200001",
  "merchant_order_no": "M-PO202605200001",
  "amount": 3000,
  "actual_amount": 3000,
  "status": "processed",
  "processed_at": "2026-05-18 15:35:00",
  "timestamp": 1779214673,
  "sign": "MD5SIGN"
}

7. 參考 HTML 欄位對照

你提供的參考 HTML 文件有部分欄位命名與目前系統不同。公開文件保留對照表，讓商戶知道目前正式 API 應送哪個欄位。

8. 錯誤碼 / 回應格式