ネイティブチェックアウト

ネイティブ統合では、Google が呼び出して購入手続きセッションを作成および管理できる RESTful API を構築する必要があります。

全体的なフローは次のとおりです。

Build checkout session（購入手続きセッションの作成）: ユーザーと（必要に応じて）エージェントが、セッションにアイテムを追加するループに入ります。
Google UI へのハンドオフ: ユーザーが購入手続きを行うことを決定すると、エージェント（エンゲージメントしている場合）は Google UI に制御を渡します（購入手続きセッションデータを渡します）。
手動購入手続き: ユーザーは Google の UI のみを使用して、配送と支払いの機密情報を入力し、注文を送信します。エージェントはこの部分に関与しないため、決定論が保証されます。
完了と戻り: Google UI に [ありがとうございました] ページが表示され、注文が確定します。必要に応じて、ユーザーはエージェントにリダイレクトされます。エージェントには、購入完了の通知がすでに届いている可能性があります。

次の手順では、実装する必要がある API エンドポイントとその動作について説明します。

1. 購入手続きセッションを作成する

このエンドポイントを使用すると、ユーザーが購入を検討している商品を含む購入手続きセッションを作成できます。

エンドポイント: POST /checkout-sessions
トリガー: ユーザーが商品の [購入] をクリックしたとき。

リクエスト: Google が広告申込情報と通貨を送信します。

{
  "line_items": [
    {
      "item": {
        "id": "product_12345", // Must match Product Feed ID
        "title": "Running Shoes"
      },
      "quantity": 1
    }
  ],
  "currency": "USD"
}

レスポンス: 合計、税金（最初は推定）、支払い機能を含む初期化されたセッションを返します。利用規約とプライバシーポリシーへのリンクを含める必要があります。これらのリンクは、お支払いボタンの下に表示されます。

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      },
      {
        "name": "dev.ucp.shopping.fulfillment",
        "version": "2026-01-11"
      }
    ]
  },
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "status": "incomplete",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000
      },
      "quantity": 1,
      "base_amount": 10000,
      "subtotal": 10000,
      "total": 10000
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 10000 }, // in cents
    { "type": "tax", "amount": 0 },
    { "type": "total", "amount": 10000 }
  ],
  "payment": {
    "handlers": [
      {
        "id": "gpay",
        "name": "com.google.pay",
        "config": {
           "api_version": 2,
           "api_version_minor": 0,
           "merchant_info": {
             "merchant_id": "12345678901234567890",
             "merchant_name": "Example Merchant"
           },
           "allowed_payment_methods": [
             {
               "type": "CARD",
               "parameters": {
                 "allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                 "allowed_card_networks": ["VISA", "MASTERCARD"]
               },
               "tokenization_specification": {
                 "type": "PAYMENT_GATEWAY",
                 "parameters": {
                   "gateway": "stripe",
                   "gateway_merchant_id": "exampleGatewayMerchantId"
                 }
               }
             }
           ]
        }
      }
    ]
  },
  "links": [
    { "type": "privacy_policy", "url": "https://m.com/privacy" },
    { "type": "terms_of_service", "url": "https://m.com/terms" }
  ]
}

2. 決済セッションを取得する

このエンドポイントを使用すると、購入手続きセッションを取得できます。

エンドポイント: GET /checkout-sessions/{id}

リクエスト: Google が購入手続きセッションの ID を送信します。グローバル ID（gid://merchant.example.com/Checkout/session_abc123）の場合、リクエストパスの ID はこの ID の最後のコンポーネントのみになります（例:session_abc123）を指定できます。

レスポンス: 完全なチェックアウトオブジェクトを返します。

3. 購入手続きセッションを更新する

このエンドポイントでは、購入手続きセッションを更新できます。配送先住所が更新された場合は、税金と配送オプションを再計算して返す必要があります。

エンドポイント: PUT /checkout-sessions/{id}
トリガー: ユーザーが配送先住所を選択または変更したとき、配送方法の選択を更新したとき、またはお支払い情報を更新したとき。

リクエスト: Google は、更新された情報を含む完全なチェックアウトオブジェクトを送信します。

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "buyer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com"
  },
  "fulfillment": {
     "methods": [
       {
         "type": "shipping",
         "destinations": [
           {
             "id": "dest_1",
             "postal_code": "94043",
             "country": "US",
             "address_locality": "Mountain View",
             "address_region": "CA"
           }
         ],
         "selected_destination_id": "dest_1"
       }
     ]
  },
  "payment": {
    "selected_instrument_id": "pi_gpay_5678",
    "instruments": [
      {
        "id": "pi_gpay_5678",
        "handler_id": "gpay",
        "type": "card",
        "brand": "mastercard",
        "last_digits": "5678",
        "rich_text_description": "Google Pay •••• 5678"
      }
    ]
  }
  // ... other fields (line_items, currency, etc.)
}

レスポンス: 必要に応じて税金と配送オプションを再計算し、完全な購入手続きオブジェクトを返します。

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "totals": [
     { "type": "subtotal", "amount": 10000 },
     { "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
     { "type": "tax", "amount": 850 },
     { "type": "total", "amount": 11350 }
  ],

  // ... other fields (line_items, currency, etc.)

  "fulfillment": {
      "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": ["line_1"],
            "selected_destination_id": "dest_1",
            "destinations": [
               {
                 "id": "dest_1",
                 "postal_code": "94043",
                 "country": "US",
                 "address_locality": "Mountain View",
                 "address_region": "CA"
               }
            ],
            "groups": [
              {
                "id": "group_1",
                "line_item_ids": ["line_1"],
                "selected_option_id": "ship_ground",
                "options": [
                  {
                    "id": "ship_ground",
                    "title": "Ground (3-5 days)",
                    "total": 500
                  },
                  {
                    "id": "ship_express",
                    "title": "Express (1-2 days)",
                    "total": 1500
                  }
                ]
              }
            ]
          }
      ]
  }
}

4. 購入手続きセッションを完了する

このエンドポイントを使用すると、購入手続きセッションを完了して注文できます。完了した購入手続きセッションを返し、注文情報を含める必要があります。この呼び出しを受信したら、支払いの処理を開始する必要があります。

エンドポイント: POST /checkout-sessions/{id}/complete
トリガー: ユーザーが [注文する] をクリックしたとき。

リクエスト: Google は、プロバイダ（Google Pay）と、購入者に関するリスクシグナルを提供します。これにより、独自の不正検出を行うことができます。

{
  "payment_data": {
    "id": "pi_gpay_5678",
    "handler_id": "gpay",
    "type": "card",
    "brand": "mastercard",
    "last_digits": "5678",
    "billing_address": {
      "postal_code": "94043",
      "address_country": "US"
    },
    "credential": {
       "type": "PAYMENT_GATEWAY",
       "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  }
}

レスポンス: 注文が完了したことを示す完全なチェックアウトオブジェクトを返します。これには、注文 ID と注文へのパーマリンク URL が含まれます。

{
  "ucp": {
      "version": "2026-01-11",
      "capabilities": [...]
  },
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "status": "completed",

  // ... other fields (line_items, currency, etc.)

  "order_id": "gid://merchant.example.com/Order/789",
  "order_permalink_url": "https://merchant.example.com/orders/789"
}

5. 決済セッションをキャンセルする

このエンドポイントは、決済セッションをキャンセルします。

エンドポイント: POST /checkout-sessions/{id}/cancel

リクエスト: Google が購入手続きセッションの ID を送信します。

レスポンス: ステータスが canceled に更新された完全なチェックアウトオブジェクトを返します。

ネイティブ チェックアウト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。