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）。

⚠️ 最常見的驗簽失敗:空格編成了 +。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（台灣銀行轉帳出款）
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": "中國信託"                     // 收款銀行
    }
  }
}

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

  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_typeTWD
original_amount / order_amount原始 / 訂單金額（兩位小數字串）
statussuccess / fail
receive_amount / fee_amount實際到帳 / 手續費
account_name / bank_account代付收款資訊（代付回調）
attach_data下單時附加資料，原樣回傳
sign驗簽用

七、訂單狀態#

狀態說明
pending待付款 / 處理中
success付款成功 / 出款完成
fail付款失敗 / 出款失敗
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帳號未開通該功能 / 未配置費率 / 該幣別+支付方式無費率
404訂單不存在（查詢接口）
406訂單號重複（cus_order_sn 已存在）
416無可用收款渠道/收款員，訂單失敗。同步配單模式下未配到收款員即回此碼（未成功建單，請重試或改期）
500系統內部錯誤，請稍後重試或聯繫我方
A+ · api.aplusmall.cash · 本文件為對接技術規範