Shop Cash 訂單資料與第三方整合

顧客在訂單上使用 Shop Cash 時，系統會將 Shop Cash 視為一種付款方式。這不是折扣、禮品卡或商店抵用金。任何剩餘的訂單餘額，將以 Shop Pay 或 Shop Pay 分期付款的方式支付。

舉例來說，若顧客在 $100 USD 的訂單中使用 $25 USD 的 Shop Cash，該訂單將包含 $25 USD 的 Shop Cash 付款，以及 $75 USD 的 Shop Pay 付款。您的訂單資料可包含同一筆訂單的多種付款方式。

若有提供閘道值，Shop Cash 會顯示為閘道值為 shop_cash 的訂單交易。Shop Cash 交易遵循標準的交易生命週期，例如授權、請款、失效及退款。Shop Cash 不使用組合式銷售交易類型。

如果顧客同時使用來自 Shop Campaign 的 Shop 優惠，由行銷活動資助的價值也會包含在同一個 shop_cash 訂單交易金額中。買家餘額和行銷活動資助部分不會顯示為獨立的訂單交易。自 2026 年 1 月起，行銷活動成本將計入您的 Shopify 帳單，而非從支付款項中扣除，因此支付款項活動中的行銷活動計費交易僅適用於在該日期前執行的行銷活動。若要進一步瞭解，請參閱「費用、Shop Campaigns 和 Shop Cash」。

匯入訂單、交易、付款、出貨作業、退款或退貨流程的第三方系統，必須將 Shop Cash 辨識為付款方式。如果系統無法辨識 Shop Cash，包含 Shop Cash 的訂單可能會匯入失敗、匯入的付款資料不完整，或者需要手動對應。

請與您的第三方系統供應商確認下列需求：

• 該系統可以支援單一訂單使用多種付款方式。
• 該系統可以將 shop_cash 對應為付款方式。
• 系統不會將 Shop Cash 視為折扣、禮品卡或商店抵用金。
• 系統會針對每一筆 Shop Cash 授權、請款、失效及退款儲存訂單交易 ID。
• 如果系統匯入的資料包含 Shop Cash 授權值，系統會儲存完整的授權值，不會將其截斷。
• 系統將授權值視為不透明字串，且不會對其進行剖析、解碼、正規化、雜湊，或推斷其中的意義。
• 系統可處理將資金退還至 Shop Pay 和 Shop Cash 的退款。
• 系統可以將 Shop Cash 支付款項交易與卡片付款交易分開核對。
• 系統不會預設交易會按照特定順序傳回。

如果您的第三方系統預設每筆訂單只有一種付款方式，請在透過該系統處理 Shop Cash 訂單之前，先聯絡供應商。

Shop Cash 交易的授權值是一個長度不固定的不透明字串。這不是簡短的卡片授權碼，而且非人類可讀的形式。

若您的 ERP、OMS 或其他第三方系統會匯入 Shop Cash 授權值，請儲存系統提供的完整值。如果可能的話，請使用長度不固定或無長度限制的文字欄位。

當您的系統儲存 Shop Cash 授權值時，請遵循下列準則：

• 請勿將該值截斷為較短的固定長度，例如 50 或 100 個字元。
• 請勿剖析或推斷值中任何部分的意義。
• 請勿使用授權值來識別用於請款、失效或退款等 API 作業的交易。

被截斷的授權值可能會導致第三方匯入，或下游的 ERP 和 OMS 處理程序失敗。

若要支援透過 Admin API 進行請款、失效和退款，請儲存訂單交易 ID 和父系交易關係。Admin API 請款和失效作業透過 parentTransactionId 識別授權交易。退款作業則透過 parentId 識別可退款的請款交易。

當應用程式或整合透過 API 發出 Shop Cash 退款時，該退款必須父系至 Shop Cash 請款交易，而非 Shop Cash 授權交易。系統會拒絕針對授權交易的退款。

退款應用程式與 Webhook 處理常式，應該識別可退款的 Shop Cash 請款交易、計算該筆請款剩餘的可退款金額，然後針對請款交易 ID 建立退款。

使用 Admin API、訂單匯出資料、支付款項匯出資料或第三方應用程式匯出資料時，請將 Shop Cash 視為付款資料。根據您使用的匯出資料或 API 資源，Shop Cash 資訊可透過付款方式、閘道、訂單交易、支付款項交易與退款資料呈現。

建立或更新整合時，請針對包含 Shop Cash 的訂單儲存以下資訊：

• 訂單 ID 及訂購名稱。
• 付款方式或閘道值 (可用時)，例如 shop_cash。
• 每筆付款交易的訂單交易 ID。
• 交易種類和狀態，例如授權、請款、退款或失效。
• 交易金額和幣別。
• 父系交易關係 (可用時)。
• 付款 ID (可用時)。
• 完整授權值 (若您的系統會匯入的話)。
• 核對支付款項時的支付款項 ID 和餘額交易 ID。
• 核對退貨時的退款交易 ID。

若要深入瞭解可用的 Admin API 欄位，請參閱 Admin API 訂單交易開發者文件。請避免在新的整合中依賴 OrderTransaction.authorizationCode 等已棄用的欄位。

以下簡化的範例顯示了一筆 100 美元的訂單，其中 75 美元透過 Shopify Payments 支付，25 美元透過 Shop Cash 支付。這些數值僅供說明之用。

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

Shop Cash 看起來可能與其他付款或促銷價值相似，但您的系統應將每個價值分開處理：

若要將包含 Shop Cash 的訂單交由第三方系統處理，請先確認以下要求：

• Shop Cash 需對應為付款方式。
• 使用 Shop Cash 和 Shop Pay 的訂單，需以這兩種付款方式匯入。
• 付款方式邏輯未假設每筆訂單僅有一種付款方式。
• 授權值需儲存為較長的不透明字串，且不被截斷。
• 退款邏輯可針對正確的請款交易進行退款。
• 退款邏輯可將資金退還至正確的付款方式。
• 支付款項核對時，可考量 Shop Cash 抵用金、退款及行銷活動等交易類型。
• 出貨作業、會計及退貨工作流程未將 Shop Cash 視為折扣。

若您使用多個系統，請針對每個接收訂單、交易、支付款項、出貨作業、退款或退貨資料的系統完成此項審查。