沃特嚴選｜商戶 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();
}

購買點數跳轉流程

商戶會員購買點數時，建議不要直接在前端組天空交易所網址，而是由商戶後端先呼叫沃特 API 的 payment-links API 取得安全跳轉資訊，再將會員導向 redirect.url。

流程

1. 商戶系統取得會員編號、會員姓名、可選電話與付款銀行帳號。
2. 商戶後端呼叫 POST /api/v1/merchant/payment-links。
3. 沃特 API 回傳可直接跳轉的 redirect_url / data.redirect_url、有效期限、第三方 session 與回調設定。
4. 商戶前端直接導向 redirect_url，會員於天空交易所選擇儲值金額。
5. 天空交易所將金額與會員資料送回沃特 API 建立收單，並進入 APP 代理匹配。
6. APP 代理或後台完成後，沃特 API POST 回調到商戶 notify_url。

取得付款通道列表

{
    "uid": "ABCDE",
    "timestamp": 1782343543,
    "sign": "0BB022070F1578EC82C32D53F7EB7601"
}

取得商戶可選固定 / 自訂金額

商戶前端顯示金額前，請由商戶後端呼叫此 API 取得後台設定的固定金額與自訂金額上下限。

{
    "uid": "ABCDE",
    "timestamp": 1782343543,
    "sign": "0BB022070F1578EC82C32D53F7EB7601"
}

{
    "ok": 1,
    "message": "success",
    "data": {
        "currency": "TWD",
        "fixed_amounts": [
            1000,
            2000,
            3000,
            5000,
            8000,
            10000
        ],
        "allow_custom": true,
        "custom_min": 1000,
        "custom_max": 30000,
        "payment_link_endpoint": "/api/v1/merchant/payment-links/amount"
    }
}

使用商戶端已選金額取得直接媒合 URL

會員在商戶端選好固定金額或自訂金額後，商戶後端帶 amount 呼叫此 API。系統會驗證金額是否符合後台設定，並回傳可直接跳轉且自動建立收單媒合的 redirect_url。

{
    "uid": "ABCDE",
    "channel": "sky_coin",
    "merchant_order_no": "TPA202606250001",
    "amount": 5000,
    "member_no": "U1001",
    "member_account": "xinlun_user_1001",
    "member_name": "測試會員",
    "member_phone": "0912345678",
    "payer_bank_name": "華南銀行",
    "payer_bank_code": "008",
    "payer_account_no": "008123456789",
    "payer_account_last5": "56789",
    "notify_url": "https://merchant.example.com/notify/collection",
    "return_url": "https://merchant.example.com/return",
    "timestamp": 1782343543,
    "extra": {
        "source": "merchant-selected-amount"
    },
    "sign": "B50ADFC8326154B6D8C21E908982DB10"
}

{
    "ok": 1,
    "message": "success",
    "url": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
    "redirect_url": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
    "payment_url": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
    "wait_url": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
    "method": "GET",
    "amount": 5000,
    "amount_mode": "fixed"
}

curl -X POST "https://api-test.wattt.asia/api/v1/merchant/payment-links/amount" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uid":"ABCDE","channel":"sky_coin","merchant_order_no":"TPA202606250001","amount":5000,"member_no":"U1001","member_account":"xinlun_user_1001","member_name":"測試會員","member_phone":"0912345678","payer_bank_name":"華南銀行","payer_bank_code":"008","payer_account_no":"008123456789","payer_account_last5":"56789","notify_url":"https://merchant.example.com/notify/collection","return_url":"https://merchant.example.com/return","timestamp":1782343543,"extra":{"source":"merchant-selected-amount"},"sign":"B50ADFC8326154B6D8C21E908982DB10"}'

取得天空交易所跳轉連結

{
    "uid": "ABCDE",
    "channel": "sky_coin",
    "merchant_order_no": "TP202606250001",
    "member_no": "U1001",
    "member_account": "xinlun_user_1001",
    "member_name": "測試會員",
    "member_phone": "0912345678",
    "member_email": "member1001@example.com",
    "payer_name": "測試會員",
    "payer_bank_name": "華南銀行",
    "payer_bank_code": "008",
    "payer_account_no": "008123456789",
    "payer_account_last5": "56789",
    "payerAccountNumber": "008123456789",
    "payeeAccountNumber": "56789",
    "notify_url": "https://merchant.example.com/notify/collection",
    "return_url": "https://merchant.example.com/return",
    "timestamp": 1782343543,
    "extra": {
        "source": "merchant-topup",
        "member_account": "xinlun_user_1001",
        "payer_account_no": "008123456789",
        "payer_account_last5": "56789"
    },
    "sign": "196129F91A0C73706C1E076E25EC35C8"
}

{
    "ok": 1,
    "message": "success",
    "url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
    "redirect_url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
    "payment_url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
    "method": "GET",
    "data": {
        "url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
        "redirect_url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
        "payment_url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
        "method": "GET",
        "channel": {
            "code": "sky_coin",
            "name": "天空交易所儲值",
            "type": "redirect",
            "method": "GET"
        },
        "merchant_order_no": "TP202606250001",
        "third_party_session": "abc123def456ghi789jkl012",
        "expires_at": "2026-06-25 07:55:43",
        "redirect": {
            "method": "GET",
            "url": "https://coin.mpglobal.asia/sky/purchase/1?third_party_session=abc123def456ghi789jkl012&third_party_order_no=TP202606250001&user_no=U1001&user_name=%E6%B8%AC%E8%A9%A6%E6%9C%83%E5%93%A1",
            "query_params": {
                "third_party_order_no": "TP202606250001",
                "user_no": "U1001",
                "user_name": "測試會員",
                "user_account": "xinlun_user_1001",
                "customer_bank_name": "華南銀行",
                "customer_bank_account": "008123456789",
                "payer_account_last5": "56789",
                "payeeAccountNumber": "56789",
                "notify_url": "https://merchant.example.com/notify/collection",
                "link_sign": "由沃特 API 產生的 HMAC-SHA256"
            }
        },
        "callback": {
            "notify_url": "https://merchant.example.com/notify/collection",
            "return_success_body": "success",
            "events": [
                "collection.completed"
            ]
        }
    }
}

curl -X POST "https://api-test.wattt.asia/api/v1/merchant/payment-links" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uid":"ABCDE","channel":"sky_coin","merchant_order_no":"TP202606250001","member_no":"U1001","member_account":"xinlun_user_1001","member_name":"測試會員","member_phone":"0912345678","member_email":"member1001@example.com","payer_name":"測試會員","payer_bank_name":"華南銀行","payer_bank_code":"008","payer_account_no":"008123456789","payer_account_last5":"56789","payerAccountNumber":"008123456789","payeeAccountNumber":"56789","notify_url":"https://merchant.example.com/notify/collection","return_url":"https://merchant.example.com/return","timestamp":1782343543,"extra":{"source":"merchant-topup","member_account":"xinlun_user_1001","payer_account_no":"008123456789","payer_account_last5":"56789"},"sign":"196129F91A0C73706C1E076E25EC35C8"}'

Swagger / OpenAPI 測試

商戶技術人員可使用 OpenAPI JSON 匯入 Postman、Insomnia 或 Swagger Editor 測試。因本系統採用自訂 sign，Swagger 測試時仍需先用 API Secret 算出簽名後填入 request。

1. 建立收單

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

Request 欄位

狀態值

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

{
    "uid": "ABCDE",
    "orderid": "COL202606250001",
    "merchant_order_no": "M-COL202606250001",
    "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": 1782343543,
    "sign": "B45FF87480B90C25DA7828FF820DF696"
}

curl -X POST "https://api-test.wattt.asia/api/v1/merchant/collections" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uid":"ABCDE","orderid":"COL202606250001","merchant_order_no":"M-COL202606250001","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":1782343543,"sign":"B45FF87480B90C25DA7828FF820DF696"}'

Response 成功範例

{
  "ok": 1,
  "message": "收單模擬資料已建立",
  "data": {
    "id": 123,
    "orderid": "COL202606250001",
    "merchant_order_no": "M-COL202606250001",
    "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": "PO202606250001",
    "merchant_order_no": "M-PO202606250001",
    "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",
    "reverse_url": "https://merchant.example.com/notify/payout-failed",
    "extra": {
        "member_no": "U1001",
        "member_name": "測試會員",
        "source": "merchant-api-test"
    },
    "timestamp": 1782343543,
    "sign": "78EA4FF0DF0FAB434CBD4DA51473598B"
}

curl -X POST "https://api-test.wattt.asia/api/v1/merchant/payouts" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uid":"ABCDE","serial_no":"PO202606250001","merchant_order_no":"M-PO202606250001","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","reverse_url":"https://merchant.example.com/notify/payout-failed","extra":{"member_no":"U1001","member_name":"測試會員","source":"merchant-api-test"},"timestamp":1782343543,"sign":"78EA4FF0DF0FAB434CBD4DA51473598B"}'

Response 成功範例

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

3. 訂單查詢

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

收單查詢

{
    "uid": "ABCDE",
    "orderid": "COL202606250001",
    "timestamp": 1782343543,
    "sign": "090EA11DCC84AAE413F86C90FCD8276D"
}

代付查詢

{
    "uid": "ABCDE",
    "serial_no": "PO202606250001",
    "timestamp": 1782343543,
    "sign": "326801CC9834721E64EA9E158244E0B1"
}

Response 範例

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

4. 餘額查詢 / 銀行列表

商戶餘額查詢

{
    "uid": "ABCDE",
    "timestamp": 1782343543,
    "sign": "0BB022070F1578EC82C32D53F7EB7601"
}

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

銀行列表

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

回調重送

{
    "uid": "ABCDE",
    "type": "collection",
    "orderid": "COL202606250001",
    "timestamp": 1782343543,
    "sign": "49D47BB110823333D39097E8178FC650"
}

5. 商品查詢

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

https://api-test.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。回調 status 僅會出現 success 或 failed。

建議代收回調格式

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

建議代付回調格式

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

7. 參考 HTML 欄位對照

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

8. 錯誤碼 / 回應格式