Shop Cash 订单数据和第三方集成

当客户在订单中使用 Shop Cash 时，系统会将 Shop Cash 视为一种付款方式，而不是折扣、礼品卡或商店抵扣额。剩余的任何订单余额需使用 Shop Pay 或 Shop Pay 分期付款进行支付。

例如，如果客户在 100 美元的订单中使用了 25 美元的 Shop Cash，那么订单中包含 25 美元的 Shop Cash 支付和 75 美元的 Shop Pay 支付。同一订单的订单数据中可以包含多种付款方式。

在有网关值的情况下，Shop Cash 会显示为具有网关值 shop_cash 的订单交易。Shop Cash 交易遵循标准的交易生命周期（例如授权、捕获、作废和退款）。Shop Cash 不使用合并销售交易类型。

如果客户还使用了来自 Shop Campaigns 的 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 视为折扣。

如果您使用多个系统，请为接收订单、交易、交易款项、发货、退款或退货数据的每个系统完成此审核。