付款流程
訂單有尚欠時,客人可以線上付款、匯款,或由承辦登記收款。不論哪一種,錢都記成同一套現金紀錄。
客人怎麼付款
| 方式 | 客人做什麼 | 什麼時候算收到 |
|---|---|---|
| 線上刷卡 | 在金流商頁面付款 | 金流商通知付款成功後 |
| ATM 虛擬帳號 | 取得帳號,再去 ATM 或網銀轉帳 | 金流商通知入帳後 |
| 匯款 | 匯到公司帳戶 | 承辦登記收款後 |
| 付款連結 | 點承辦傳來的連結,免登入付款 | 金流商通知付款成功後 |
| 現場現金 | 交給承辦 | 承辦登記收款後 |
只有「現金紀錄」才代表錢真的收到了。客人從金流商頁面被導回、拿到 ATM 帳號,都還不是收款證明。
一筆款項怎麼變成收款
- 系統依收款計畫建立一筆收款,例如訂金 3,000。
- 客人被導到金流商頁面付款。
- 金流商把結果通知系統。系統驗證簽章並核對金額,才記一筆現金紀錄。
- 訂單的已收與尚欠立即更新。
同一筆通知重送不會重複入帳。一筆收款成功後就結束;下一期的尾款或補款是另一筆新的收款。
公司開啟「暫停新付款」時,系統不產生新的付款頁面,已送出的付款與通知照常處理。設定方式見公司設定。
ATM 虛擬帳號
ATM 付款分兩步:先取號,客人再去繳費。取號時還沒有收到錢,要等入帳通知。
逾期沒繳時:
- 訂金或全額:訂單仍待付款時,系統取消訂單,釋回席次或房晚。
- 尾款:只有這次取號失效。訂單不取消,客人可以重新付款。
›收款、付款嘗試與現金紀錄的欄位
| 階段 | 是什麼 | 在訂單上 |
|---|---|---|
| 收款 | 打算收的一筆錢,還不是收到 | intents[] |
| 付款嘗試 | 一次實際付款(導頁或人工) | 不在訂單回應裡 |
| 現金紀錄 | 真正收到或退出的現金,報表基準 | transactions[] |
訂單的現金紀錄會顯示「交易編號」與「廠商訂單編號」。transactions[].providerTradeNo 是金流商交易編號,transactions[].merchantTradeNo 是該筆付款嘗試送給金流商的廠商訂單編號。兩者都不同於 toko 訂單編號。同一張訂單的多筆付款可以有不同的廠商訂單編號;缺少資料時顯示「—」,API 回傳 null。
金流商的導回網址只把客人帶回結果頁,付款結果以通知為準。結帳時系統記下原特店與憑證版本;之後換金鑰、換特店或解除綁定,舊付款的通知仍用原版本驗證。
尾款怎麼收
在「後台 → 公司設定 → 付款設定 → 尾款收款方式」設定:
- 收款方式:「匯款」或「線上付款」。選匯款時,客人在前台看到尾款金額、期限與匯款帳戶。行程有設訂金時,前台只能付訂金。
- 匯款帳戶:國內團與海外團各選一個,依行程的海外團標記帶入。請先在收款帳戶填好完整銀行資訊;資訊不完整時,客人會看到聯絡承辦的提示。
- 抽籤團中籤後繳尾款天數:抽籤梯次的尾款期限是中籤當天加這個天數。
收尾款通知可以用 {{尾款期限}}、{{匯款銀行}}、{{匯款帳號}}、{{匯款戶名}} 變數。沒有期限時,{{尾款期限}} 原樣保留。匯款模式下,{{繳款連結}} 開啟匯款資訊。
訂單頁的付款連結
在訂單頁「款項」分頁,可以產生三種連結傳給客人:
| 連結 | 用在 |
|---|---|
| 補尾款連結 | 已付訂金、要收尾款的訂單 |
| 尾款刷卡連結 | 客人要求刷卡付尾款。免登入,金額是目前尾款,只適用這張訂單 |
| 自填金額付款連結 | 多人分攤時,各自填金額付款。免登入,連結只顯示一次 |
付款成功後,金流商通知系統自動入帳。自填金額連結同時有兩人付款、超過尚欠時,兩筆都照收,訂單變成多付,再走退款處理。
同一分頁也可以「寄尾款繳款單」給訂購人。同業訂單不寄。國旅卡要在外部後台開連結,確認入帳後再登記收款。
候補中的訂單、抽籤未中籤的訂單、梯次已取消的訂單,這三種連結與尾款繳款單都不能產生。客人在前台也不能自助繳尾款。
登記人工收款
匯款、現金等不經金流商的收款,由承辦登記:
-
在訂單頁「款項」分頁按「登記手動收款」。也可以在「後台 → 款項 → 收款紀錄」按「手動建立收款」,用訂單編號查詢。
-
選實際收到款項的收款帳戶。系統不會依國內或海外自動帶入。
-
填金額。留空時結清全部尚欠。
-
依帳戶種類填憑據:
收款帳戶 必填憑據 銀行帳戶 入帳日期與匯款末五碼。臨櫃存款改勾臨櫃。 金流商帳戶 金流訂單編號 現金帳戶 無 -
按確定登記。
規則:
- 已取消的訂單不能登記。已出團的訂單仍可登記尾款。
- 已收齊的訂單不再入帳。
- 金額不能超過尚欠。
一筆匯款付多張訂單:在登記對話框按「改用合併匯款登記」,輸入匯款總額,再分配到各張訂單。分配合計必須等於匯款總額。
撤銷登記錯的收款
登記錯的人工收款,在訂單頁的「人工登記的收款」撤銷。撤銷後,已收、尚欠與付款狀態重新計算;原收款保留並標成已撤銷,另記一筆反向紀錄。
- 管理員隨時可以撤銷。
- 登記人在時限內可以自己撤銷。過了時限,改按「申請撤銷收款」,由管理員核准。
- 時限在「後台 → 公司設定 → 付款設定 → 撤銷人工收款」設定。填 0 表示登記人一律要送申請。
›人工收款 API
POST /orders/{id}/mark-paid 登記收款。receivingAccountId 必填。指定 amountTwd 只收該金額,省略則結清全部尚欠。
{
"receivingAccountId": "<accountId>",
"amountTwd": 3000,
"idempotencyKey": "payment-20261013-001",
"bankReference": "12345",
"bankCreditedOn": "2026-10-13"
}CLI:toko orders mark-paid <id> --amount-twd 3000 --idempotency-key payment-20261013-001 --bank-reference 12345 --bank-credited-on 2026-10-13 --receiving-account <accountId> --confirm。
- 憑據:銀行帳戶要
bankCreditedOn與bankReference(上限 40 字),臨櫃改送overTheCounter: true;金流商帳戶要providerTradeNo。缺了回422 validation。 - 重送同一筆收款沿用同一個
idempotencyKey(8 至 64 字英數或連字號),不重複入帳,回idempotent: true、collectedTwd: 0。 - 已取消的訂單回
409 conflict。已收齊的訂單回成功但不入帳:idempotent: true、collectedTwd: 0。 - 金額須為正整數。超過尚欠、收款計畫不足或未知欄位回
422。 - 回應有本次入帳
collectedTwd、入帳後的customerCashAppliedTwd、outstandingTwd與paymentState。
合併匯款用 POST /orders/split-remittance,憑據規則相同。各單金額加總須等於 totalTwd。
{
"totalTwd": 3000,
"allocations": [
{ "orderId": "<orderId1>", "amountTwd": 1000 },
{ "orderId": "<orderId2>", "amountTwd": 2000 }
],
"receivingAccountId": "<accountId>",
"idempotencyKey": "split-20261013-001"
}CLI:toko orders split-remittance --data '<上述 JSON>' --confirm。
retentionDeferred:收款、建單、調整、沖正、合併匯款、換梯確認、抽籤裁決、住宿代訂與排房、取消訂單、標記退款已付等回應都有這個欄位。值為 true 表示操作已完成,但客戶維繫資料尚未同步,每日排程會補做。不要因此重送。
收款紀錄的對帳狀態:收款列的 reconciliationTransactions 逐筆列出入帳交易。matched 已配對、pending 待對帳、unassigned 未歸戶、unsupported 帳戶種類或幣別不支援。pendingReconciliationCount 是待對帳的入帳交易數。
舊系統收款明細:完成逐筆整理的舊收款會出現在收款列表與 GET /api/v1/payments/export。provider 是 legacy,每筆有帳戶、用途與歷史入帳時間。日期篩選使用歷史入帳日。id 是舊收款明細識別碼,不能用來操作金流商。退款另見退款紀錄或梯次收款匯出。
撤銷人工收款只有後台入口。
選擇金流商
在「後台 → 公司設定 → 付款設定」設定。需要管理員權限。
- 可以設定綠界、PAYUNi、藍新、永豐豐收款,也可以只用人工收款。
- 各家設定可以同時保留,新付款只走一家預設金流商。
- 正式環境目前只能用綠界收款。 收款前要先設定你的綠界憑證。未設定時收款會被擋下,不會改用平台的帳號。
- 憑證加密保存,儲存後不再顯示。
- PAYUNi、藍新、永豐要填手續費率。新付款記下當時的費率,實際手續費以對帳為準。
- 切換、換金鑰、換特店都只影響新付款。舊的付款頁、ATM 帳號、通知與退款,仍用原本的金流商與特店。
- 解除綁定只停止新收款。
- 每家金流商支援的付款方式由平台維護。沒啟用的付款方式不會出現在結帳畫面。
PayNow 的付款通知無法驗證來源,ATM 繳費期限也沒有精確時間,所以暫不開放 PayNow 收款。
›金流商設定 API
- 查詢:
GET /api/v1/settings/payment-provider,回傳預設金流商、支援功能與憑證遮罩。CLI:toko settings payment-provider --json。 - 變更:
PUT /api/v1/settings/payment-provider,帶明確的operation:configure、change_merchant、rotate_key、unlink、fee_policy或switch。設定、換金鑰與換特店都要送完整憑證。
{ "operation": "switch", "provider": "payuni" }CLI:toko settings set-payment-provider --operation switch --provider payuni --confirm。
- 永豐用
provider: "sinopac",merchantId是銀行的 ShopNo,憑證是hashA1、hashA2、hashB1、hashB2與xKey。永豐建立付款的結果不明時,禁止自動重送,先查詢核對;信用卡要確認請款完成才入帳。 - PayNow 的憑證是交易密碼
transactionPassword。 - 綠界憑證也可用 settings API 設定。重送同一筆付款時,綠界每次用新的交易編號,系統會處理。
- 無法還原原特店或憑證的舊交易,保留待核對,不用目前帳號猜補,也不自動刷退。
- 開發與測試環境另有模擬付款;正式環境沒有。
換梯時的付款
換梯會讓舊的付款連結與 ATM 帳號失效,改依新應收建立新的付款入口。
- 舊 ATM 帳號只保留歷史,不再顯示為繳費資訊。
- 換梯前已在付款中的款項,若稍後才通知成功,仍入同一張訂單一次。多出來的錢開退款草稿,不直接退。
- 訂購人在訂單頁可以看到累計收款、已退還、目前待付與待處理的退款。
詳見換梯與拆單。
代收轉付電子收據
旅行社代收的團費,可以開立代收轉付電子收據。在「後台 → 款項 → 代收轉付」開立、折讓、作廢收據,查詢收據狀態與報稅總表。
設定步驟:
- 在「後台 → 公司設定 → 公司資料」填統一編號。收據平台的特店代號就是統一編號。
- 在「後台 → 公司設定 → 付款設定 → 代收轉付 travelinvoice 憑證」填 HashKey 與 HashIV。
- 要自動開立時,打開「自動開立、折讓與作廢」。
開啟自動開立後,系統每天 06:30 處理:
- 付清的訂單開收據。出團日還沒到的,先預約開立。
- 減少應收的退款開折讓。
- 取消的訂單作廢收據。
自動開立只開給訂購人(二聯),還不讀訂單的收據分配表。要開統編的三聯收據,請到代收轉付頁手動開立。開啟前的訂單與退款不會補做。
訂單收據分配表
每張訂單有一張收據分配表,記錄收據怎麼開:幾張公司收據(抬頭、統編、寄送 Email、金額),加上最後一張訂購人個人收據。個人收據的金額由系統算:應收減公司收據加總。
- 客人在結帳的確認送出步填:勾「需要開公司抬頭收據(統編)」,可以加好幾張。會員用過的統編會記下來,下次結帳可以選,也可以在會員中心刪除。
- 客人在會員中心的訂單頁可以改到出發日前一天。出發日當天起要改,請客人聯絡你們。
- 承辦在 K 單的「代收轉付收據」段填。同業單預設一張同業的公司收據,金額等於應收。
- 業務、OP 與會計在訂單頁「款項 → 收據分配」隨時可以改。每次修改留稽核紀錄。
- 統編要過財政部檢查碼。公司收據加總不能超過應收。
應收變多時,多的算進個人收據。應收變少時,先從個人收據扣。扣到 0 還不夠,訂單標「收據分配要重排」:訂單頁款項分頁頂端有提示,工作台有待辦,請重新分配。
›收據分配表 API
GET /orders/{id} 回應的 receiptAllocation 帶整張表:rows(公司收據在前,最後一列 isOrderer: true 是個人收據)、receivableTwd、companyTotalTwd、needsReorder、excessTwd。GET /orders 與匯出可以用 receipt=needs_reorder 只列要重排的訂單。POST /orders 建 K 單時可以帶 receiptAllocation;檢查不過回 422,整張單不建立。
換梯不會自動作廢收據,多付退回也不代表收據已修正。換梯前先處理收據。
›代收轉付 API
travelinvoice API 可以開立、查詢、同步、折讓與作廢收據。金額由訂單計算。收據平台回應不明時,先用 POST /travelinvoice/{id}/sync 查狀態,再決定要不要重試。
匯出梯次收款明細
在梯次總覽的「更多」選單選「匯出收款明細」。也可以選「檢視收款紀錄」,在收款頁先看該梯次,再下載。
- 每列是一筆實際收款。失敗或待付款的不列。
- 退款與沖正用負數另列,附退款執行方式與出款帳戶。
- 欄位有訂購人、同單旅客姓名、收款用途、金額、收款帳戶、付款方式、入帳日、匯款末五碼、對帳狀態,以及訂單目前的應收、累計已收與未收。最後一欄是登記時間。
- 入帳日是登記收款時填的銀行入帳日期(YYYY-MM-DD)。沒有填這個日期的收款(例如金流收款、退款),入帳日是登記時間的日期。
- 累計已收不扣退款,退款另列,避免重複扣減。
- 完成逐筆整理的舊單,按歷史入帳日列出各筆帳戶與用途。原整單彙總不重複列入。
- 沒有收款時,只有標題列。
›匯出 API
GET /api/v1/departures/{depId}/payments-export 回傳標準 JSON。data.filename 是檔名,data.csv 是 UTF-8 BOM 的 CSV。在 Google Apps Script 可讀 data.csv,用 Utilities.parseCsv 解析。需要 payment.read,並遵守訂單讀取範圍。
收款、退款、出款不要混用
相關指南
- 訂單與金流模型:應收、已收與狀態。
- 取消與退款:退款單與刷退。
- 收款帳戶與對帳結算:收款帳戶與對帳。
- payments API · orders API。