一、接口地址#

用途	地址
代收提交	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）。

⚠️ 最常見的驗簽失敗:空格編成了 +。URL-encode 有兩種:表單式（PHP urlencode() / 線上「URL 編碼」工具）空格是 +;我方簽名用的是 RFC 3986（PHP rawurlencode() / JS encodeURIComponent() / Java URLEncoder.encode(...).replace("+","%20")），空格是 %20。
例:任何含空格的 value（如英文姓名 John Smith）驗簽時必須把空格拼成 %20（John%20Smith），不是 +（John+Smith）。

範例

參數：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	選	付款人真實姓名（實名欄位），用於實名比對。要送實名一律用此欄位；attach_data 只是附加資料（原樣回調返回、對帳用），非實名欄位

響應

{
  "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（台灣銀行轉帳出款）
bank_account	✓	收款銀行帳號
bank_code	✓	收款銀行名稱。不限定格式，以下皆可：3 碼代號（822）、中文名稱（中國信託）、或兩者併寫（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": "中國信託"                     // 收款銀行
    }
  }
}

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

1. 下單 /api/payment/deposit 取得 order_sn（此時 payment_detail 可能為空）。
2. 每 2~3 秒輪詢 /api/payment/info，直到回出 payment_detail（或 payment_img）。
3. 取得收款帳戶後展示給付款人；或直接導向 payment_uri（我方收銀台，配好會自動顯示）。
4. 輪詢到 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（成功）/ cancel（已取消，由客服人工取消，等同該筆未完成）。本站訂單不會進入 fail。
receive_amount / fee_amount	實際到帳 / 手續費
bank_account	代付收款帳號（代付回調）
attach_data	下單時附加資料，原樣回傳
message	success / cancelled（不含空格；判斷成敗請以 status 為準）
sign	驗簽用

七、訂單狀態#

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

八、對接流程#

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

九、錯誤碼#

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

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

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

附錄、銀行對照表（台灣）#

代付 bank_code 不限定格式（3 碼代號 / 中文名稱 / 822 中國信託 併寫皆可）， 本表僅供對照參考。共 295 筆，資料為台灣金融機構代號。 我方不校驗此欄，內容不足以辨識銀行時僅能在出款階段才發現，請盡量以本表的代號或名稱為準。