toko

付款流程

訂單有尚欠時,客人可以線上付款、匯款,或由承辦登記收款。不論哪一種,錢都記成同一套現金紀錄。

客人怎麼付款

方式客人做什麼什麼時候算收到
線上刷卡在金流商頁面付款金流商通知付款成功後
ATM 虛擬帳號取得帳號,再去 ATM 或網銀轉帳金流商通知入帳後
匯款匯到公司帳戶承辦登記收款後
付款連結點承辦傳來的連結,免登入付款金流商通知付款成功後
現場現金交給承辦承辦登記收款後

一筆款項怎麼變成收款

  1. 系統依收款計畫建立一筆收款,例如訂金 3,000。
  2. 客人被導到金流商頁面付款。
  3. 金流商把結果通知系統。系統驗證簽章並核對金額,才記一筆現金紀錄。
  4. 訂單的已收與尚欠立即更新。

同一筆通知重送不會重複入帳。一筆收款成功後就結束;下一期的尾款或補款是另一筆新的收款。

公司開啟「暫停新付款」時,系統不產生新的付款頁面,已送出的付款與通知照常處理。設定方式見公司設定。

ATM 虛擬帳號

ATM 付款分兩步:先取號,客人再去繳費。取號時還沒有收到錢,要等入帳通知。

逾期沒繳時:

  • 訂金或全額:訂單仍待付款時,系統取消訂單,釋回席次或房晚。
  • 尾款:只有這次取號失效。訂單不取消,客人可以重新付款。
›收款、付款嘗試與現金紀錄的欄位
階段是什麼在訂單上
收款打算收的一筆錢,還不是收到intents[]
付款嘗試一次實際付款(導頁或人工)不在訂單回應裡
現金紀錄真正收到或退出的現金,報表基準transactions[]

訂單的現金紀錄會顯示「交易編號」與「廠商訂單編號」。transactions[].providerTradeNo 是金流商交易編號,transactions[].merchantTradeNo 是該筆付款嘗試送給金流商的廠商訂單編號。兩者都不同於 toko 訂單編號。同一張訂單的多筆付款可以有不同的廠商訂單編號;缺少資料時顯示「—」,API 回傳 null。

金流商的導回網址只把客人帶回結果頁,付款結果以通知為準。結帳時系統記下原特店與憑證版本;之後換金鑰、換特店或解除綁定,舊付款的通知仍用原版本驗證。

尾款怎麼收

在「後台 → 公司設定 → 付款設定 → 尾款收款方式」設定:

  • 收款方式:「匯款」或「線上付款」。選匯款時,客人在前台看到尾款金額、期限與匯款帳戶。行程有設訂金時,前台只能付訂金。
  • 匯款帳戶:國內團與海外團各選一個,依行程的海外團標記帶入。請先在收款帳戶填好完整銀行資訊;資訊不完整時,客人會看到聯絡承辦的提示。
  • 抽籤團中籤後繳尾款天數:抽籤梯次的尾款期限是中籤當天加這個天數。

收尾款通知可以用 {{尾款期限}}、{{匯款銀行}}、{{匯款帳號}}、{{匯款戶名}} 變數。沒有期限時,{{尾款期限}} 原樣保留。匯款模式下,{{繳款連結}} 開啟匯款資訊。

訂單頁的付款連結

在訂單頁「款項」分頁,可以產生三種連結傳給客人:

連結用在
補尾款連結已付訂金、要收尾款的訂單
尾款刷卡連結客人要求刷卡付尾款。免登入,金額是目前尾款,只適用這張訂單
自填金額付款連結多人分攤時,各自填金額付款。免登入,連結只顯示一次

付款成功後,金流商通知系統自動入帳。自填金額連結同時有兩人付款、超過尚欠時,兩筆都照收,訂單變成多付,再走退款處理。

同一分頁也可以「寄尾款繳款單」給訂購人。同業訂單不寄。國旅卡要在外部後台開連結,確認入帳後再登記收款。

候補中的訂單、抽籤未中籤的訂單、梯次已取消的訂單,這三種連結與尾款繳款單都不能產生。客人在前台也不能自助繳尾款。

登記人工收款

匯款、現金等不經金流商的收款,由承辦登記:

  1. 在訂單頁「款項」分頁按「登記手動收款」。也可以在「後台 → 款項 → 收款紀錄」按「手動建立收款」,用訂單編號查詢。

  2. 選實際收到款項的收款帳戶。系統不會依國內或海外自動帶入。

  3. 填金額。留空時結清全部尚欠。

  4. 依帳戶種類填憑據:

    收款帳戶必填憑據
    銀行帳戶入帳日期與匯款末五碼。臨櫃存款改勾臨櫃。
    金流商帳戶金流訂單編號
    現金帳戶無
  5. 按確定登記。

規則:

  • 已取消的訂單不能登記。已出團的訂單仍可登記尾款。
  • 已收齊的訂單不再入帳。
  • 金額不能超過尚欠。

一筆匯款付多張訂單:在登記對話框按「改用合併匯款登記」,輸入匯款總額,再分配到各張訂單。分配合計必須等於匯款總額。

撤銷登記錯的收款

登記錯的人工收款,在訂單頁的「人工登記的收款」撤銷。撤銷後,已收、尚欠與付款狀態重新計算;原收款保留並標成已撤銷,另記一筆反向紀錄。

  • 管理員隨時可以撤銷。
  • 登記人在時限內可以自己撤銷。過了時限,改按「申請撤銷收款」,由管理員核准。
  • 時限在「後台 → 公司設定 → 付款設定 → 撤銷人工收款」設定。填 0 表示登記人一律要送申請。
›人工收款 API

POST /orders/{id}/mark-paid 登記收款。receivingAccountId 必填。指定 amountTwd 只收該金額,省略則結清全部尚欠。

json
{
  "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。

json
{
  "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。設定、換金鑰與換特店都要送完整憑證。
json
{ "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 帳號只保留歷史,不再顯示為繳費資訊。
  • 換梯前已在付款中的款項,若稍後才通知成功,仍入同一張訂單一次。多出來的錢開退款草稿,不直接退。
  • 訂購人在訂單頁可以看到累計收款、已退還、目前待付與待處理的退款。

詳見換梯與拆單。

代收轉付電子收據

旅行社代收的團費,可以開立代收轉付電子收據。在「後台 → 款項 → 代收轉付」開立、折讓、作廢收據,查詢收據狀態與報稅總表。

設定步驟:

  1. 在「後台 → 公司設定 → 公司資料」填統一編號。收據平台的特店代號就是統一編號。
  2. 在「後台 → 公司設定 → 付款設定 → 代收轉付 travelinvoice 憑證」填 HashKey 與 HashIV。
  3. 要自動開立時,打開「自動開立、折讓與作廢」。

開啟自動開立後,系統每天 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,並遵守訂單讀取範圍。

收款、退款、出款不要混用

事情錢的方向在哪裡處理
跟客人收款收進來本篇
退錢給客人退出去取消與退款
付錢給供應商、嚮導、佣金付出去請款與出款批次

相關指南

Command Palette

Search for a command to run...