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 Campaign の Shop オファーも使用した場合、キャンペーン負担分の金額は同じ shop_cash の注文取引金額に含まれます。購入者の残高分とキャンペーン負担分は、別個の注文取引としては表示されません。 2026 年 1 月以降、キャンペーンの費用は支払いから差し引かれるのではなく Shopify の請求に計上されるため、支払いアクティビティにおけるキャンペーンの請求取引は、その日付より前に実施されたキャンペーンにのみ適用されます。詳細については、 手数料、 Shop Campaigns 、 Shop Cash を参照してください。

注文、取引、決済、フルフィルメント、返金、または返品をインポートする外部システムは、 Shop Cash を決済方法として認識する必要があります。システムが Shop Cash を認識しない場合、 Shop Cash を含む注文のインポートに失敗したり、決済データが不完全な状態でインポートされたり、手動でのマッピングが必要になったりする可能性があります。

外部システムのプロバイダーとともに、以下の要件を確認してください。

• システムが 1 つの注文で複数の決済方法をサポートできること。
• システムが shop_cash を決済方法としてマッピングできること。
• システムが Shop Cash をディスカウント、ギフトカード、またはストアクレジットとして処理しないこと。
• システムが、 Shop Cash の各承認、売上確定、無効化、および返金に対して注文の取引 ID を保存すること。
• インポートするデータに Shop Cash の承認値が含まれている場合、システムがその値を切り捨てずに完全な承認値を保存すること。
• システムが承認値を不透明な文字列として処理し、解析、デコード、正規化、ハッシュ化、またはそこから意味を推測したりしないこと。
• システムが、 Shop Pay と Shop Cash の両方に資金を戻す返金を処理できること。
• システムが、 Shop Cash の支払い取引をカード決済の取引とは別に照合できること。
• システムが、取引が特定の順序で返されることを前提としないこと。

外部システムが各注文に 1 つの決済方法しかないことを前提としている場合は、そのシステムで 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 order transaction の開発者ドキュメントを参照してください。新しい統合については、OrderTransaction.authorizationCode などの非推奨のフィールドに依存しないようにします。

次の簡略化された例は、100米ドルの注文のうち、75米ドルが Shopify ペイメント で、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 を使用した注文が、両方の決済方法としてインポートされていること。
• 決済方法のロジックが、1つの注文に対して決済方法を1つのみと想定していないこと。
• オーソリの値が長い不透明な文字列として保存され、切り捨てられていないこと。
• 返金ロジックにより、正しいキャプチャ取引に対して返金できること。
• 返金ロジックにより、正しい決済方法に資金を返却できること。
• 支払いの照合により、Shop Cash のクレジット、返金、キャンペーンの取引タイプを処理できること。
• フルフィルメント、会計、返品のワークフローにおいて、Shop Cash がディスカウントとして扱われていないこと。

複数のシステムを使用している場合は、注文、取引、支払い、フルフィルメント、返金、または返品のデータを受信する各システムについて、この確認を行ってください。