Implementierung der nativen Checkout REST API

In diesem Leitfaden finden Sie die technische API-Referenz und die Nutzlastschemas für Version 2026-04-08 des nativen Direktkaufs des Universal Commerce Protocol (UCP).

Bevor Sie Ihre Endpunkte erstellen, sollten Sie sich die Übersicht über den nativen Direktkauf ansehen, um sich über den allgemeinen Bezahlvorgang, die Authentifizierungsanforderungen und die Entwicklertools zu informieren.

Direktkaufsitzung erstellen

Mit diesem Endpunkt kann eine Checkout-Sitzung mit den Produkten erstellt werden, die ein Nutzer kaufen möchte.

  • Endpunkt:POST /checkout-sessions
  • Auslöser:Der Nutzer klickt bei einem Produkt auf „Jetzt kaufen“ oder im Warenkorb auf „Mit Google bezahlen“.

Anfrage:Google sendet die Positionen und eingeschränkte Adressinformationen zum Käufer, einschließlich Ort, Bundesland und Postleitzahl.

// Request Example: Create checkout with multiple items.
{
  "line_items": [
    {
      "item": {
        // Must match ID in product feed
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      "item": {
        // Must match ID in product feed
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1"
      }
    ]
  }
}

Antwort:Sie geben die initialisierte Sitzung mit Summen, Steuern (anfänglich geschätzt) und Zahlungsfunktionen zurück.

Hinweis zum Feld ucp.status:

Das Feld ucp.status wurde in Version 2026-04-08 eingeführt und gibt das Ergebnis der Erstellung an:

  • "success" (oder ausgelassen): Standardeinstellung. Sitzung erstellt, auch mit wiederherstellbarem messages.
  • "error":Die Sitzung konnte aufgrund eines nicht behebaren Fehlers nicht erstellt werden (z.B. sind alle Artikel nicht auf Lager). In diesem Fall sollte der Antworttext ein Error Response-Objekt und kein Checkout-Objekt sein. Ein Beispiel für einen nicht behebaren Fehler finden Sie im Abschnitt „Fehlerbehandlung“ unter Beispiel für einen nicht behebaren Fehler.

Hinweis zu Änderungen am totals-Array:

  • Das Feld type in jedem Objekt im Array totals ist jetzt ein offener String.
  • Das Feld amount kann jetzt negativ sein, z.B. um Rabatte darzustellen.
  • Objekte in totals (z. B. type: "fee" und type: "tax") können optional ein lines-Array enthalten, um Unterkomponenten aufzuschlüsseln (z. B. Service- oder Recyclinggebühren oder mehrstufige Aufschlüsselungen von Steuern auf Provinz- und Bundesebene wie die kanadische GST, PST oder QST).
  • Preise inklusive Steuern:In Märkten, in denen Steuern im Preis enthalten sind, muss die subtotal Steuern enthalten. Die Position tax sollte ausgelassen werden und display_text sollte explizit für die Einträge subtotal und fulfillment in totals angegeben werden. Weitere Informationen finden Sie unter Preise inklusive Steuern.
// Response Example: Initialize Session with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "path": "$.buyer",
      "content_type": "plain",
      "content": "Buyer information is required for checkout",
      "severity": "recoverable"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "path": "$.fulfillment.methods[0].destinations[0]",
      "content_type": "plain",
      "content": "Shipping address is incomplete",
      "severity": "recoverable"
    }
  ],
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 10000
        },
        {
          "type": "total",
          "amount": 10000
        }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2500
        },
        {
          "type": "total",
          "amount": 2500
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
      "amount": 12500 // Tax-inclusive markets: Amount must include tax.
    },
    {
      "type": "fee",
      "display_text": "Fees",
      "amount": 549,
      "lines": [
        { "display_text": "Service Fee", "amount": 399 },
        { "display_text": "Recycling Fee", "amount": 150 }
      ]
    },
    {
      "type": "fulfillment",
      "display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
      "amount": 500
    },
    {
      "type": "tax", // Tax-inclusive markets: Omit this entry.
      "display_text": "Estimated Tax",
      "amount": 1050
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 14599
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 500} ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 1500} ]
              }
            ],
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

Preise einschließlich Steuern

In Märkten, in denen die Steuer im angezeigten Zwischensumme enthalten ist und nicht separat aufgeschlüsselt wird, muss Ihre Implementierung die folgenden Anforderungen erfüllen, wenn Sie Daten zur Checkout-Sitzung bereitstellen:

  • Steuern in die Zwischensumme einbeziehen:Das Feld amount für den Eintrag subtotal muss alle anfallenden Steuern enthalten.
  • Separate Steuereinträge weglassen:Fügen Sie kein separates Objekt mit type: "tax" in das totals-Array ein.
  • Benutzerdefinierten Anzeigetext angeben:Sie müssen im Zwischensummenobjekt das Attribut display_text einfügen, in dem explizit angegeben wird, dass Steuern enthalten sind, z. B. "Subtotal (including taxes)". Sie müssen auch ein display_text-Attribut für Einträge zur Ausführung angeben (z.B. "Shipping").

Beispiel: Array mit Gesamtwerten inklusive Steuern

Das folgende Beispiel zeigt ein totals-Array für einen Händler in einem Markt, in dem Steuern im Preis enthalten sind:

"totals": [
  {
    "type": "subtotal",
    "display_text": "Subtotal (including taxes)",
    "amount": 12500
  },
  {
    "type": "fulfillment",
    "display_text": "Shipping",
    "amount": 399
  },
  {
    "type": "total",
    "display_text": "Total",
    "amount": 12899
  }
]

Mehrstufige Aufschlüsselung von Steuern

Für Märkte, in denen detaillierte Steuerangaben für mehrere Ebenen oder Gerichtsbarkeiten erforderlich sind (z. B. die kanadische GST oder HST auf Bundesebene und die PST oder QST auf Provinzebene), können Sie ein type: "tax"-Objekt auf oberster Ebene mit einem verschachtelten lines-Array angeben:

  • Steuer auf oberster Ebene zusammenfassen:Gibt ein einzelnes zusammengefasstes tax-Objekt mit der Gesamtsteuer amount und einer beschreibenden display_text (z.B. "Taxes") zurück.
  • Aufschlüsselung nach Positionen:Einzelne Steuerkomponenten im lines-Array mit den entsprechenden display_text (z.B. "TPS / GST (5%)", "TVQ / QST (9.975%)") und amount aufschlüsseln.
  • Invariant:Die Summe aller Beträge der untergeordneten Zeilen muss dem amount des übergeordneten tax-Eintrags entsprechen.

Beispiel: Steueraufschlüsselung nach mehreren Stufen

{
  "type": "tax",
  "display_text": "Taxes",
  "amount": 1498,
  "lines": [
    { "display_text": "TPS / GST (5%)", "amount": 500 },
    { "display_text": "TVQ / QST (9.975%)", "amount": 998 }
  ]
}

Checkout-Sitzung abrufen

Mit diesem Endpunkt kann eine Checkout-Sitzung abgerufen werden.

  • Endpunkt:GET /checkout-sessions/{id}

Anfrage:Google sendet die ID der Abrechnungssitzung. Wenn Sie globale IDs verwenden (z.B. gid://merchant.example.com/Checkout/session_abc123), ist die ID im Anfragepfad nur die letzte Komponente dieser ID (z.B. session_abc123).

Antwort:Sie geben das vollständige Checkout-Objekt zurück. Bei einer Sitzung mit mehreren Artikeln, die unter Version 2026-01-23 oder höher erstellt wurde, enthält das line_items-Array mehrere Posteinträge.

Direktkaufsitzung aktualisieren

Mit diesem Endpunkt können Sie eine Checkout-Sitzung aktualisieren. Wenn die Versandadresse aktualisiert wird, müssen Steuern und Versandoptionen neu berechnet und zurückgegeben werden.

  • Endpunkt:PUT /checkout-sessions/{id}

Versandadresse aktualisieren

  • Auslöser:Der Nutzer wählt seine Versandadresse aus oder ändert sie.

Anfrage:Google aktualisiert die Versandadresse, wenn der Nutzer seine Versandadresse ändert.

// Request Example: Update shipping address with multiple items.
{
  "line_items": [
    {
      // line_items id from Create Checkout response
      "id": "line_1",
      "item": {
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      // line_items id from Create Checkout response
      "id": "line_2",
      "item": {
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

Antwort:Sie berechnen Steuern und Versandoptionen nach Bedarf neu und geben das vollständige Checkout-Objekt zurück.

// Response Example: Updated session with new address for multiple items.
{
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     // Shipping cost might change based on new address
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
     {
       "type": "fee",
       "display_text": "Fees",
       "amount": 549,
       "lines": [
         { "display_text": "Service Fee", "amount": 399 },
         { "display_text": "Recycling Fee", "amount": 150 }
       ]
     },
     // Tax will likely change based on new address
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  }
  // ... other fields like ucp, status, messages, links
}

Vollständige Datenübertragung des Checkout-Objekts

Anfrage:Google sendet das vollständige Checkout-Objekt mit den aktualisierten Informationen (einschließlich der vollständigen Lieferadresse und der Kontaktdaten des Käufers), wenn der Käufer auf „Mit GPay bezahlen“ klickt.

// Request Example: full checkout object hydration for multiple items.
{
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_12345" },
      "quantity": 1
    },
    {
      "id": "line_2",
      "item": { "id": "product_67890" },
      "quantity": 1
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

Antwort:Sie berechnen Steuern und Versandoptionen nach Bedarf neu und geben das vollständige Checkout-Objekt zurück.

// Response Example: Session after full hydration with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "ready_for_complete",
  "currency": "USD",
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
      {
        "type": "fee",
        "display_text": "Fees",
        "amount": 549,
        "lines": [
          { "display_text": "Service Fee", "amount": 399 },
          { "display_text": "Recycling Fee", "amount": 150 }
        ]
      },
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

Zahlungsvorgang abschließen

Mit diesem Endpunkt kann eine Checkout-Sitzung abgeschlossen und eine Bestellung aufgegeben werden. Es sollte die abgeschlossene Checkout-Sitzung zurückgeben und die Bestellinformationen enthalten. Die Zahlungsabwicklung sollte erst nach Erhalt dieses Anrufs beginnen.

Anfrage:Google sendet das ausgewählte Zahlungsmittel vom Zahlungsabwickler, einschließlich der Anmeldedaten (z.B. Google Pay-Tokenisierungsdaten) und Risikosignale zum Käufer, damit Sie Ihre eigene Betrugserkennung durchführen können. Der Inhalt des Tokens hängt von Ihrem Zahlungsdienstleister ab.

{
  "payment": {
    "instruments": [
      {
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        },
        "credential": {
          "token": "examplePaymentMethodToken",
          "type": "PAYMENT_GATEWAY"
        },
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "selected": true,
        "type": "card"
      }
    ]
  },
  "signals": {
    "com.google.authentication_triggered": "",
    "com.google.authorization_processed_with_3ds": "",
    "com.google.avs_full_result": "",
    "com.google.cvv_result": "",
    "com.google.ip_address": "203.0.113.1",
    "dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
    "dev.ucp.buyer_ip": "203.0.113.1"
  }
}

Wenn Sie für den Abschluss der Kaufabwicklung obligatorische Informationen benötigen, die in der Checkout-Sitzung nicht angegeben wurden, können Sie den Abschluss der Kaufabwicklung verhindern und diese Informationen anfordern, indem Sie in der Antwort einen Status zurückgeben, der nicht „complete“ ist.

Wenn Google die fehlenden Informationen mithilfe von UCP-definierten Feldern (z. B. E-Mail-Adresse des Käufers) erfassen kann, setzen Sie status auf incomplete und fügen Sie dem Array messages eine oder mehrere Nachrichten hinzu, in denen severity auf recoverable gesetzt ist und angegeben wird, welche Informationen fehlen.

{
  "ucp": {
    "version": "2026-04-08",
    "status": "success"
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "severity": "recoverable",
      "content": "Buyer email is required"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "severity": "recoverable",
      "content": "Select delivery window for your purchase"
    }
  ]
}

Wenn Sie ein Google Pay-Zahlungsmittel erhalten, müssen Sie Folgendes tun:

  1. Handler validieren:Bestätigen Sie, dass handler_id dem in Ihrer Konfiguration definierten Google Pay-Zahlungshandler entspricht.
  2. Token extrahieren:Rufen Sie das generierte Zahlungsmethoden-Token aus payment.instruments[0].credential.token ab.
  3. Zahlung verarbeiten:Verwenden Sie das Token und die Transaktionsdetails, um die Zahlung abzuschließen. Hier finden Sie die Google Pay API-Dokumentation mit detaillierten Informationen zur Tokenisierungs-Spezifikation und ‑Verarbeitung.

Antwort:Wenn der Zahlungsvorgang abgeschlossen und die Zahlung verarbeitet wurde, geben Sie das vollständige Zahlungsvorgangsobjekt zurück, das angibt, dass die Bestellung abgeschlossen ist. Dazu gehören das bestätigte Zahlungsmittel (mit Metadaten des Zahlungsmittels und Rechnungsadresse, ohne das vertrauliche credential-Token oder signals), die Bestell-ID und eine Permalink-URL zur Bestellung.

{
  "ucp": {
      "version": "2026-04-08",
      "status": "success",
      "capabilities": [...]
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "completed",

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

  "payment": {
    "instruments": [
      {
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "card",
        "selected": true,
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        }
      }
    ]
  },
  "order": {
    "id": "ORD1773956535.2727807",
    // Example customer-facing order number
    "label": "#100",
    "permalink_url": "https://merchant.example.com/orders/789"
  }
}

Checkout-Sitzung abbrechen

Mit diesem Endpunkt wird eine Checkout-Sitzung abgebrochen.

  • Endpunkt:POST /checkout-sessions/{id}/cancel

Anfrage:Google sendet die ID der Abrechnungssitzung.

Antwort:Sie geben das vollständige Checkout-Objekt mit dem auf canceled aktualisierten Status zurück.

Fehlerbehandlung

Vollständige Richtlinien zur Formatierung von Fehlermeldungen und zur Unterscheidung zwischen Protokoll- und Geschäftslogikfehlern finden Sie in der Übersicht über Fehlercodes.

Nicht behebbarer Fehler

Ab Version 2026-04-08 müssen Sie bei einem nicht behebbarer Fehler, der die Erstellung einer Checkout-Sitzung verhindert (z.B. wenn alle Artikel nicht vorrätig sind), den HTTP-Fehlercode 200 OK zurückgeben. Legen Sie im Antworttext "status": "error" im Objekt ucp fest. Dies teilt Google mit, dass die Anfrage gültig war, aber die Erstellung der Sitzung durch eine Geschäftsregel blockiert wurde. In diesem Fall wird keine Checkout-Sitzungs-ID zurückgegeben.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error"
  },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}