Für die native Integration müssen Sie eine RESTful API erstellen, die Google aufrufen kann, um Check-out-Sitzungen zu erstellen und zu verwalten.
Der allgemeine Ablauf sieht so aus:
- Checkout-Sitzung erstellen:Der Nutzer und optional ein Agent fügen der Sitzung in einer Schleife Artikel hinzu.
- Übergabe an eine Google-Benutzeroberfläche:Wenn der Nutzer sich für die Abrechnung über den Agenten entscheidet (falls er mit dem Agenten interagiert), wird die Steuerung an eine Google-Benutzeroberfläche übergeben (die Abrechnungssitzungsdaten werden übergeben).
- Manuelle Kaufabwicklung:Der Nutzer interagiert jetzt nur noch mit der Google-Benutzeroberfläche, um vertrauliche Versand- und Zahlungsdetails einzugeben und die Bestellung aufzugeben. Der Agent ist an diesem Teil nicht beteiligt, was für Determinismus sorgt.
- Abschluss und Rückgabe:In der Google-Benutzeroberfläche wird eine „Danke“-Seite angezeigt, um die Bestellung zu bestätigen. Optional kann der Nutzer zurück zum Kundenservicemitarbeiter weitergeleitet werden, der möglicherweise bereits über den abgeschlossenen Kauf informiert wurde.
In den folgenden Schritten werden die API-Endpunkte beschrieben, die Sie implementieren müssen, und ihr Verhalten.
1. Direktkauf-Sitzung erstellen
Mit diesem Endpunkt kann eine Checkout-Sitzung mit den Produkten erstellt werden, die ein Nutzer kaufen möchte.
- Endpunkt:
POST /checkout-sessions - Trigger:Der Nutzer klickt bei einem Produkt auf „Kaufen“.
Anfrage:Google sendet die Werbebuchungen und die Währung.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Antwort:Sie geben die initialisierte Sitzung mit Summen, Steuern (anfänglich geschätzt) und Zahlungsfunktionen zurück. Sie müssen Links zu Ihren Nutzungsbedingungen und Ihrer Datenschutzerklärung einfügen, die unter der Zahlungs-Schaltfläche verlinkt werden.
{
"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. Bezahlsitzung 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). Die ID im Anfragepfad ist nur die letzte Komponente dieser ID (z. B.
session_abc123) verwenden.
Antwort:Sie geben das vollständige Checkout-Objekt zurück.
3. Checkout-Sitzung 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} - Auslöser:Der Nutzer wählt seine Versandadresse aus oder ändert sie, aktualisiert seine Versandoptionen oder aktualisiert seine Zahlungsinformationen.
Anfrage:Google sendet das vollständige Direktkauf-Objekt mit den aktualisierten Informationen.
{
"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.)
}
Antwort:Sie berechnen Steuern und Versandoptionen nach Bedarf neu und geben das vollständige Checkout-Objekt zurück.
{
"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. Bezahlvorgang 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.
- Endpunkt:
POST /checkout-sessions/{id}/complete - Trigger:Der Nutzer klickt auf „Bestellung aufgeben“.
Anfrage:Google sendet das Zahlungs-Token (verschlüsselter Blob) vom Anbieter (z.B. Google Pay) und Risikosignale zum Käufer, damit Sie Ihre eigene Betrugserkennung durchführen können.
{
"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\"...}"
}
}
}
Antwort:Sie geben das vollständige Checkout-Objekt zurück, das angibt, dass die Bestellung abgeschlossen ist, einschließlich der Bestell-ID und einer Permalink-URL zur Bestellung.
{
"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. 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.