A+ · 開發者文件

A+ 商戶開發者文件

幣別 TWD（新台幣） · 台灣本地銀行轉帳 · Base URL https://api.aplusmall.cash

所有接口支援 POST / GET，Content-Type: application/x-www-form-urlencoded。請先向我方取得商戶號 cus_code 與密鑰 secret_key。 回調來源 IP 54.199.155.234 請務必放行，否則收不到回調。本站僅支援 台灣銀行轉帳（無支付寶／微信／人民幣）。

一、接口地址#

用途	地址
代收提交	`POST /api/payment/deposit`
代收查詢	`POST /api/payment/info`
代付提交	`POST /api/charge/receive`
代付查詢	`POST /api/charge/info`
餘額查詢	`POST /api/inquire/account/info`

二、簽名規則#

參數依 key 字母序排序、排除空值與 sign、value 做 URL-encode（空格編為 %20）、末尾接 &key=<secret_key>，整串取 MD5 小寫。金額固定兩位小數（如 1000.00）。

範例

參數：cus_code=MCH001, cus_order_sn=T20260921001, payment_flag=bank_twd, amount=1000.00
待簽字串：
amount=1000.00&cus_code=MCH001&cus_order_sn=T20260921001&payment_flag=bank_twd&key=你的密鑰
sign = md5(上面字串) 小寫

三、代收下單 `/api/payment/deposit`#

參數	必填	說明
`cus_code`	✓	商戶號
`cus_order_sn`	✓	貴司訂單號（唯一）
`payment_flag`	✓	`bank_twd`（台灣銀行轉帳）
`amount`	✓	金額（TWD，兩位小數字串）
`notify_url`	選	回調地址（不帶則用商戶預設）
`payer_name`	選	付款人姓名（有助配對/對帳）

響應

{
  "result": 1, "status": "200", "message": "Success",
  "order_info": {
    "order_sn": "A...",                 // 我方訂單號
    "cus_order_sn": "T20260921001",
    "currency_type": "TWD",
    "order_amount": "1000.00",
    "payment_uri": "https://cashier.aplusmall.cash/pay/xxxx",  // 收銀台，交付款人
    "order_status": "pending",
    "expired_at": "...", "created_at": "..."
  }
}

⚠️ 代收收款帳戶由我方配單完成後才產生（見「五、查詢接口」），下單響應僅回 payment_uri；可直接把付款人導向 payment_uri，或輪詢查詢取得收款帳戶自行顯示。

四、代付下單 `/api/charge/receive`#

參數	必填	說明
`cus_code` / `cus_order_sn` / `amount` / `sign`	✓	同代收
`payment_flag`	✓	`pay_bank_twd`（台灣銀行轉帳出款）
`account_name`	✓	收款人姓名
`bank_account`	✓	收款銀行帳號
`bank_code`	✓	收款銀行代碼（台灣 3 碼銀行代號，如 822 中國信託）
`notify_url` / `attach_data`	選	回調地址 / 附加資料（原樣回傳）

五、查詢接口#

代收查詢 /api/payment/info、代付查詢 /api/charge/info、餘額查詢 /api/inquire/account/info。查詢參數：cus_code + order_sn（我方訂單號）+ sign。

代收查詢響應（含收款資訊）

{
  "result": 1, "status": "200",
  "order_info": {
    "order_sn": "A...", "cus_order_sn": "T...",
    "order_amount": "1000.00", "receive_amount": "1000.00",
    "order_status": "pending",                 // pending 待付款 / success 成功 / cancel 取消
    "payment_uri": "https://cashier.aplusmall.cash/pay/xxxx",
    "payment_img": "https://.../qr.png",       // 收款 QR（有則顯示）
    "payment_detail": {                          // 收款帳戶（配好後才有）
      "account_name": "王小明",                  // 收款人姓名
      "account_no": "0000000000000",            // 收款銀行帳號
      "bank_name": "中國信託"                     // 收款銀行
    }
  }
}

⚠️ 收款帳戶為配單後產生 — 請輪詢查詢

下單 /api/payment/deposit 取得 order_sn（此時 payment_detail 可能為空）。
每 2~3 秒輪詢 /api/payment/info，直到回出 payment_detail（或 payment_img）。
取得收款帳戶後展示給付款人；或直接導向 payment_uri（我方收銀台，配好會自動顯示）。
輪詢到 order_status = success 即到帳（以異步回調為準），停止輪詢。

六、異步回調（notify_url）#

我方以 POST 推送結果到貴司 notify_url（來源 IP 54.199.155.234，請放行）。驗簽方式與下單一致。貴司處理成功後須回傳純文字 success，否則我方會重試。

欄位	說明
`order_sn` / `cus_order_sn`	我方 / 貴司訂單號
`currency_type`	`TWD`
`original_amount` / `order_amount`	原始 / 訂單金額（兩位小數字串）
`status`	`success` / `fail`
`receive_amount` / `fee_amount`	實際到帳 / 手續費
`account_name` / `bank_account`	代付收款資訊（代付回調）
`attach_data`	下單時附加資料，原樣回傳
`sign`	驗簽用

七、訂單狀態#

狀態	說明
`pending`	待付款 / 處理中
`success`	付款成功 / 出款完成
`fail`	付款失敗 / 出款失敗
`cancel`	已取消

八、對接流程#

貴司放行回調 IP 54.199.155.234、提供 notify_url。
我方開通商戶號，回傳 cus_code + secret_key。
先代收／代付各一筆小額測試單，確認回調與驗簽通過後上量。

九、錯誤碼#

接口失敗時回統一結構（HTTP 200，以 result 判斷）：

{ "result": "error", "status": 416, "message": "...", "request_data": null }

status	說明
`300`	金額錯誤（金額 ≤ 0，或手續費大於訂單金額）
`400`	缺少必填參數
`401`	驗簽失敗 / 商戶不存在 / 無權訪問該訂單
`403`	帳號未開通該功能 / 未配置費率 / 該幣別+支付方式無費率
`404`	訂單不存在（查詢接口）
`406`	訂單號重複（`cus_order_sn` 已存在）
`416`	無可用收款渠道/收款員，訂單失敗。同步配單模式下未配到收款員即回此碼（未成功建單，請重試或改期）
`500`	系統內部錯誤，請稍後重試或聯繫我方

A+ · api.aplusmall.cash · 本文件為對接技術規範