跳到主要內容
ZH
登入 註冊
文件

官方資料

zittme Pay 模組

zittme Pay 是 Zittme 的金流閘道模組。它集中處理電商・預約等其他模組的付款，並提供付款明細・取消・日誌管理。第三方模組只要遵循既定規範，也能透過 zittme Pay 串接付款。

安裝

  1. 從商店安裝 zittme Pay 模組。
  2. 在 管理員 > zittme Pay 使用 設定・閘道・付款明細・日誌 分頁。

    3. 設定分頁全部項目

    項目說明
    使用開啟/關閉整體付款功能
    測試模式不進行實際授權，檢查付款流程。閘道金鑰也請使用測試金鑰
    幣別預設 KRW
    訂單編號前綴用來在金流業者管理後台辨識我方訂單的標記（英文・數字 8 個字元以內）
    允許部分取消是否可只取消部分付款金額。關閉時只能全額取消
    取消原因清單取消時選擇的原因。每行輸入一個
    金流自動取消期限（天）付款後超過此期間，就不再嘗試向金流業者取消，改為手動退款。這是因為已完成清算的信用卡付款無法透過金流業者取消。0 表示不限制
    允許強制取消已確認交易讓管理員也能取消已確認購買的付款。關閉時，確認後無論透過任何途徑都無法取消
    管理員通知電子郵件通知收件地址
    通知事件付款完成時 / 取消時是否分別發送
    日誌保存天數付款日誌保存期間（0=無限期）
    Webhook IP 允許清單限制可接收閘道 Webhook 的 IP。留空表示不限制
    付款畫面告示文字顯示在付款畫面底部的文字，例如通訊販賣業申報編號等
    付款畫面面板選擇付款・結果畫面的面板

    閘道分頁（付款方式）

    開啟要使用的付款方式，並輸入各方式的資訊。

    Toss Payments（信用卡等）

    項目說明
    用戶端金鑰於 Toss Payments 開發者中心核發
    密鑰同上。請絕對不要對外洩漏

    建議先以測試金鑰 + 測試模式確認流程，再換成正式金鑰。金鑰種類（測試/正式）與模式不一致時，授權會失敗。

    KG Inicis

    項目說明
    商店 ID（MID）於 Inicis 特約商店管理後台核發
    Sign Key用於付款視窗簽章
    INIAPI Key取消・退款專用金鑰。需另外在特約商店管理後台申請

    在測試模式下，即使尚未簽約，也能用公開測試商店（mid INIpayTest）的金鑰確認到付款視窗為止。若授權通訊中斷或金額不符，會自動進行網路取消，防止重複扣款。

    NHN KCP

    項目說明
    網站代碼（site_cd）由 KCP 核發。測試用為 T0000
    服務憑證將從 KCP 管理後台認證中心取得的 PEM 檔案內容原封不動貼上
    商店私鑰・密碼只用於取消・退款請求的電子簽章

    NICEPAY

    項目說明
    Client ID於 NICEPAY 開發者中心（developers.nicepay.co.kr）核發
    Secret Key同上

    只要註冊開發者中心就能取得沙盒金鑰，簽約前也能測試付款・取消流程。開啟測試模式時會自動連線到沙盒伺服器。

    PortOne（V2）

    項目說明
    Store ID於 PortOne 主控台（portone.io）核發
    通道金鑰要透過哪家金流業者付款，由 PortOne 主控台的通道設定決定
    V2 API Secret用於伺服器授權・取消

    一個驅動程式即可使用串接在 PortOne 上的多家金流業者。測試時填入測試通道的金鑰即可。

    PayPal（海外付款）

    項目說明
    Client ID・Secret於 PayPal 開發者主控台（developer.paypal.com）的應用程式中核發。測試模式下使用沙盒應用程式金鑰
    付款幣別PayPal 不支援 KRW。會將韓元訂單換算成此幣別付款（預設 USD）

    換算時使用下方的共用匯率，退款則以付款當時的匯率處理。外幣訂單（電商多幣別）不經換算，直接以該幣別付款。

    Conekta（墨西哥・中南美洲）

    透過墨西哥金流業者 Conekta 的託管付款頁面，接受信用卡、現金（OXXO 超商）、銀行轉帳（SPEI）。按下付款後會前往 Conekta 付款頁面，付款完成後回到網站。現金與銀行轉帳只會核發參考編號或帳號，並以「等待匯款」狀態返回，實際入帳由 Webhook 確認。

    項目說明
    Conekta 私密金鑰在 Conekta 面板 > Desarrolladores > API Keys 建立的私密金鑰（以 key_ 開頭）。不使用公開金鑰
    Webhook 網址將畫面上顯示的網址登錄到 Conekta 面板 > Desarrolladores > Webhooks。現金・銀行轉帳的入帳確認必須用到
    付款方式選擇付款頁面要開放的方式。信用卡 / 現金（OXXO）/ 銀行轉帳（SPEI）。留空則全部開放
    付款幣別換算韓元訂單時使用的幣別。預設 MXN。OXXO 與 SPEI 只支援 MXN，USD 信用卡付款則視 Conekta 帳戶類型開放
    允許韓元訂單開啟後，會以共用匯率換算韓元訂單並付款。匯率表中必須有付款幣別（MXN）的列

    取得測試金鑰

    1. 註冊 panel.conekta.com 後，進入「Explorar panel」（瀏覽面板），無需商家審核即會建立測試公司。
    2. 開啟左下角的「Modo pruebas」（測試模式），在 Desarrolladores > 「Consultar API Keys de prueba」中以「Crear nueva llave privada」建立私密金鑰。私密金鑰只會在建立當下顯示一次，請立即複製。
    3. 在閘道分頁填入私密金鑰並按「連線測試」，就會顯示模式（沙盒 / 正式交易）。測試金鑰沒有特別的前綴，因此模式由 Conekta 的回應判定。在建立第一筆訂單之前，可能會顯示為「需要確認」。
    4. 在 Desarrolladores > Webhooks > 「Crear Webhook」填入上述 Webhook 網址，並開啟所有事件。無論收到哪種事件，zittme Pay 都會透過 Conekta API 重新查詢訂單再確認，因此偽造的通知無法讓付款成立。

      5. 測試付款

      • 核准卡：4242 4242 4242 4242（Visa）、5555 5555 5555 4444（Mastercard）。姓名與 CVC 可填任意值，到期日填未來日期。
      • 拒絕卡：4000 0000 0000 0002，餘額不足：4000 0000 0000 0127。
      • 銀行轉帳（SPEI）可使用核發的 CLABE 呼叫 Conekta 的沙盒入帳通知 API（/sandbox/spei/payment_notifications），即會完成入帳處理。現金（OXXO）在沙盒中會於稍後自動完成入帳處理。

      正式交易金鑰

      依 Conekta 條款，正式交易帳戶需要依墨西哥法律設立的商家（持有 RFC）與墨西哥清算帳戶。審核完成後，只要將面板上的正式交易金鑰填入同一欄位即可。只有信用卡付款能透過 API 退款，現金・銀行轉帳付款會轉為手動退款。

      銀行轉帳

      項目說明
      匯款帳戶可登錄多組銀行・帳號・戶名。買家在下單時選擇帳戶
      匯款期限（天）1~30 天。超過期限仍未匯款的交易會成為自動取消對象

      入帳確認由管理員在付款明細中處理，確認後串接模組的訂單會轉為付款完成。

      共用匯率

      在閘道分頁管理各幣別的匯率（每 1 單位幣別兌換多少 KRW）。zittme Pay 的付款換算與電商模組的多幣別價格共同參照這個值，是唯一的基準。

      項目說明
      匯率表登錄幣別代碼（USD 等）與匯率
      手動固定勾選的幣別不會被自動更新覆蓋
      自動更新每天更新 1 次。來源可選 open.er-api.com（不需金鑰）或韓國進出口銀行（需要 API 金鑰）

      即使自動更新失敗，也會保留最後一次成功的值；訂單會儲存付款當時的匯率，不受之後匯率變動影響。

      外幣付款

      當電商等串接模組傳來外幣訂單時，會以該幣別付款。不支援訂單幣別的付款方式不會出現在付款畫面上（韓國國內金流業者僅支援 KRW，PayPal 支援 24 種主要幣別）。金額標示會依幣別符號與小數位數自動處理。

      付款流程

      1. 在串接模組（電商等）的訂單頁選擇付款方式並按下付款。
      2. 信用卡：在 Toss Payments 付款視窗授權 → 結果畫面。/ 銀行轉帳：顯示帳戶資訊與匯款期限的結果畫面 → 管理員確認入帳後即付款完成。
      3. 付款狀態變更會立即反映到串接模組，也會透過閘道 Webhook 進行雙重確認。

        4. 訂單編號與付款編號

        買家若看到兩個編號容易混淆，因此依以下原則標示。

        編號核發標示
        訂單編號請求付款的模組（電商・預約等）在付款畫面・結果畫面・明細中作為主要編號大字顯示
        付款編號zittme Pay作為輔助小字顯示。付款洽詢・取消處理的依據

        付款明細與取消

        • 付款明細：依狀態・期間・付款方式搜尋所有付款交易，並逐筆查看授權資訊・串接模組的訂單編號・處理紀錄。
        • 取消：在交易中執行全額或部分取消（允許時）。信用卡付款會將取消傳送至閘道，銀行轉帳則記錄為退款處理。取消原因從設定中的原因清單選擇。
        • 超過金流自動取消期限的交易：會引導您改以手動退款處理，而非向金流業者取消。
        • 日誌：記錄閘道請求/回應與 Webhook 接收，超過保存期間後會清除。調查付款問題時查看。

        如何閱讀日誌

        日誌分頁會依時間順序累積與金流業者往來的內容。付款失敗或入帳未確認時，請從這裡開始查看。

        回應欄會顯示一行摘要，而非原始內容。

        • 金流業者有回傳失敗原因時，會直接顯示該文字。例如 카드 한도 초과、유효하지 않은 카드번호 這類內容。
        • 銀行轉帳交易會整理顯示核發的帳戶・匯款人姓名・匯款期限。
        • 沒有可摘要的內容時，會截取原始內容的前段顯示。

        需要完整原始內容時，請將滑鼠移到摘要文字上，就會顯示金流業者回傳的原始回應。提出洽詢時請附上這段原始內容。

        若回應為空白，表示請求未能送達金流業者。請確認閘道分頁的驗證資訊，以及伺服器是否封鎖對外連線。

        第三方模組串接（開發者）

        其他模組串接 zittme Pay 付款的規範很簡單。

        1. 呼叫建立付款（createOrder）時，在 source_code 參數傳入自己模組的訂單編號。
        2. 如此一來，付款畫面・結果畫面・管理明細會以該編號作為「訂單編號」主要顯示，zittme Pay 的代碼則標示為「付款編號」。
        3. 在付款完成・取消回呼中更新自己模組的訂單狀態。

          4. 電商與預約模組是此規範的參考實作。模組開發的一般規範請一併參閱開發者指南中的「模組製作」文件。

          常見問題

          • 測試付款無法進行：請確認是否為測試模式，以及 Toss Payments 金鑰是否為測試金鑰。
          • 銀行轉帳訂單一直是等待付款：銀行轉帳必須由管理員按下入帳確認才會變成付款完成。設定匯款期限後，放置未匯款的交易會自動整理。
          • 看不到部分取消按鈕：若設定中的允許部分取消為關閉，就只能全額取消。
          • 舊的信用卡付款取消失敗：金流業者已完成清算的交易無法取消信用卡付款。請依金流自動取消期限設定，改以手動退款處理。
          • 收不到 Webhook：請確認 Webhook IP 允許清單中沒有漏掉閘道的 IP。留空則不限制接收。
          • 新的付款方式沒有出現在付款畫面：必須在閘道分頁開啟該方式並填入金鑰才會出現。金鑰空白時不會顯示在清單中。
          • PayPal 無法啟用：除了 Client ID・Secret 之外，共用匯率中也必須登錄付款幣別（預設 USD）的匯率。
          • 更換付款畫面面板後又變回原樣：已在 0.2.0 修正。請更新模組。
          • 付款完成返回後出現「此請求無法使用的 HTTP 方法」：這是 0.2.9 以下版本使用 Conekta・PortOne 這類付款視窗跳轉到其他網站、再以 GET 返回的金流業者時會發生的問題。從 0.2.10 起回呼可同時接收 GET・POST，請到 管理員 > 資源庫 更新 zittme Pay。付款本身已在金流業者端正常處理，因此發生錯誤的訂單只要在付款明細中重新查詢，就會同步為已授權狀態。