Der Bezahlvorgang wird gestartet, wenn ein Nutzer einen Einkaufswagen erstellt. Der Inhalt des Einkaufswagens des Nutzers und Details zur Bestellung werden an den End-to-End-Webdienst für Bestellungen gesendet. Diese Informationen werden von Ihrem Webdienst validiert. Sie können dann entweder fortfahren oder den Warenkorb nach Bedarf anpassen.
Der Checkout-Handler für Ihren Webdienst muss auf POST-Anfragen antworten. Wenn ein Kunde zur Kasse gelangt, sendet Google dem Bestell-End-to-End-Webdienst einen JSON-Anfragetext in Form eines CheckoutRequestMessage, das die Details der Cart eines Kunden enthält. Der Webdienst antwortet dann mit einer CheckoutResponseMessage. Das folgende Diagramm veranschaulicht den Vorgang.
Wenn Sie eine Zahlungsanforderung erhalten, muss Ihr End-to-End-Webdienst für Bestellungen Folgendes tun:
- Prüfen Sie die Gültigkeit des Einkaufswagens anhand aktueller Artikelpreise, Verfügbarkeit und Anbieterservice.
- Berechnen Sie den Gesamtpreis (einschließlich aller Rabatte, Steuern und Liefergebühren).
- Wenn der Vorgang erfolgreich war, antworten Sie mit einem unveränderten Einkaufswagen.
- Wenn der Vorgang nicht erfolgreich war, antworten Sie mit einer Fehlermeldung und einem neuen Bestellvorschlag.
Bevor Sie mit der Implementierung des Bezahlvorgangs beginnen, sollten Sie die Dokumentation Auftragsausführung – Übersicht lesen.
Nachricht zur Zahlungsanforderung
Zur Validierung des Einkaufswagens des Kunden sendet Google beim Bezahlvorgang eine Anfrage mit einem JSON-Text in Form eines CheckoutRequestMessage an Ihren Webdienst. Die Kundenbestellung wird erst später im End-to-End-Ablauf des Bestellvorgangs eingereicht.
In einem CheckoutRequestMessage enthaltene Daten umfassen Folgendes:
- Intent: Das Feld
inputs[0].intentjeder Checkout-Anfrage enthält den Stringwertactions.foodordering.intent.CHECKOUT. - Einkaufswagen: Das Feld
inputs[0].arguments[0].extensioneiner Zahlungsanfrage enthält einCart-Objekt, das den Einkaufswagen des Kunden darstellt. - Lieferung oder Essen zum Mitnehmen: Das Erweiterungsfeld des
Cart-Objekts enthält einFoodCartExtension-Objekt, das Eigenschaften für Lieferung oder Essen zum Mitnehmen angibt:- Bei Lieferbestellungen enthält das
FoodCartExtension-Objekt die Lieferadresse. - Für Bestellungen zum Abholen oder Essen zum Mitnehmen enthält das
FoodCartExtension-Objekt keine Standortinformationen.
- Bei Lieferbestellungen enthält das
- Sandbox: Das Feld
isInSandboxeiner Zahlungsanfrage enthält einen booleschen Wert, der angibt, ob für die Transaktion Sandbox-Zahlungen verwendet werden.
Beispiel für eine Checkout-Anfrage
Hier sehen Sie ein Beispiel für eine CheckoutRequestMessage:
{
"user": {},
"conversation": {
"conversationId": "CTZbZfUlHCybEdcz_5PB3Ttf"
},
"inputs": [
{
"intent": "actions.foodordering.intent.CHECKOUT",
"arguments": [
{
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.Cart",
"merchant": {
"id": "restaurant/Restaurant/QWERTY",
"name": "Tep Tep Chicken Club"
},
"lineItems": [
{
"name": "Spicy Fried Chicken",
"type": "REGULAR",
"id": "299977679",
"quantity": 2,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "39",
"nanos": 600000000
}
},
"offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": -33.8376441,
"longitude": 151.0868736
},
"formattedAddress": "Killoola St, 1, Concord West NSW 2138",
"zipCode": "2138",
"city": "Concord West",
"postalAddress": {
"regionCode": "AU",
"postalCode": "2138",
"administrativeArea": "NSW",
"locality": "Concord West",
"addressLines": [
"Killoola St",
"1"
]
}
}
}
}
}
]
}
],
"directActionOnly": true,
"isInSandbox": true
}
Antwortnachricht für den Bezahlvorgang
Nachdem Sie eine Anfrage vom End-to-End-Dienst für Bestellungen erhalten haben, muss Ihr Checkout-Webdienst diese verarbeiten und mit einer CheckoutResponseMessage antworten. CheckoutResponseMessage muss entweder eine erfolgreiche oder nicht erfolgreiche Anfrage abdecken.
Anfrage erfolgreich
Wenn eine Check-out-Anfrage erfolgreich ist, muss CheckoutResponseMessage ProposedOrder und PaymentOptions enthalten:
ProposedOrdercart: Eincart-Objekt, das mit dem inCheckoutRequestMessagebereitgestellten Einkaufswagen identisch ist. Wenn einer der Inhalte des Einkaufswagens geändert werden muss, sollteCheckoutResponseMessagestattdessen einenFoodErrorExtensionmit einem korrigiertenProposedOrderenthalten.otherItems: Vom Anbieter hinzugefügte Elemente, z. B. Versandkosten, Steuern und andere Gebühren. Kann auch Trinkgeld enthalten, das vom Nutzer hinzugefügt wurde.totalPrice: Der Gesamtpreis der Bestellung.extension: EinFoodOrderExtension, der Informationen zur Auftragsausführung für die Bestellung definiert, z. B. die Lieferdauer.
PaymentOptions- Das Einrichten der Zahlungsabwicklung wird später unter Google Pay einrichten beschrieben.
Sie können die Platzhalter-JSON-Datei in Ihrem
CheckoutResponseMessageverwenden, bis Sie zur Implementierung der Zahlungsverarbeitung bereit sind. - Informationen zum Hinzufügen von Platzhalterzahlungsoptionen in deiner
CheckoutResponseMessagefindest du im Beispiel unten. Dort wird ein Beispiel für ein Zahlungs-Gateway fürPaymentOptionsverwendet.
- Das Einrichten der Zahlungsabwicklung wird später unter Google Pay einrichten beschrieben.
Sie können die Platzhalter-JSON-Datei in Ihrem
Beispiel für eine erfolgreiche Antwort
{
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"checkoutResponse": {
"proposedOrder": {
"cart": {
"merchant": {
"id": "restaurant/Restaurant/QWERTY",
"name": "Tep Tep Chicken Club"
},
"lineItems": [
{
"name": "Spicy Fried Chicken",
"type": "REGULAR",
"id": "299977679",
"quantity": 2,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "39",
"nanos": 600000000
}
},
"offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": -33.8376441,
"longitude": 151.0868736
},
"formattedAddress": "Killoola St, 1, Concord West NSW 2138",
"zipCode": "2138",
"city": "Concord West",
"postalAddress": {
"regionCode": "AU",
"postalCode": "2138",
"administrativeArea": "NSW",
"locality": "Concord West",
"addressLines": [
"Killoola St",
"1"
]
}
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "43",
"nanos": 100000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
}
]
},
"otherItems": [
{
"name": "Delivery fee",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
}
]
},
"paymentOptions": {
"googleProvidedOptions": {
"facilitationSpecification": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"merchantName\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\"],\"allowedCardNetworks\":[\"VISA\",\"MASTERCARD\"],\"billingAddressRequired\":true,\"cvcRequired\":false},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gatewayMerchantId\":\"YOUR_MERCHANT_ID\",\"gateway\":\"cybersource\"}}}],\"transactionInfo\":{\"currencyCode\":\"AUD\",\"totalPriceStatus\":\"ESTIMATED\",\"totalPrice\":\"43.1\"}} "
}
},
"additionalPaymentOptions": [
{
"actionProvidedOptions": {
"paymentType": "ON_FULFILLMENT",
"displayName": "Pay when you get your food.",
"onFulfillmentPaymentData": {
"supportedPaymentOptions": []
}
}
}
]
}
}
}
]
}
}
}
Anfrage fehlgeschlagen
Wenn eine Checkout-Anfrage nicht erfolgreich ist, muss CheckoutResponseMessage FoodErrorExtension enthalten. Sie enthält eine Liste von FoodOrderError-Elementen, die aufgetretene Fehler beschreiben. Wenn bei der Bestellung behebbare Fehler auftreten, z. B. eine Preisänderung bei einem Artikel im Einkaufswagen, muss FoodErrorExtension den Parameter correctedProposedOrder enthalten.
Beispiel für eine nicht erfolgreiche Antwort
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"error": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
"foodOrderErrors": [
{
"error": "CLOSED",
"description": "The restaurant is closed."
}
]
}
}
}
]
}
}
}
Implementierung des Bezahlvorgangs
Die folgenden Schritte sollten beim Implementieren des Bezahlvorgangs durchgeführt werden.
Dienst validieren
Für die erste gefundene Dienstfehlerbedingung wird ein FoodOrderError zurückgegeben. Diese Fehler können nicht behoben werden, sodass der erste aufgetretene Fehler zurückgegeben werden sollte. Eine Beschreibung der behebbaren Fehler finden Sie unter Umgang mit Fehlern.
- Lesen Sie das Attribut FulfillmentOptionInfo in der Anfrage, um festzustellen, ob der Auftragsausführungstyp
deliveryoderpickupist. Geben Sie bei Bedarf die folgenden Fehlertypen zurück:
Fehlertyp Anwendungsfall INVALID Der Auftragsausführungstyp ist ungültig. NOT_FOUND Der Auftragsausführungstyp wurde nicht gefunden. GESCHLOSSEN - Für den Auftrag gibt es keine OperationHours-Fenster.
- Es handelt sich um einen Auftrag vom Typ „ASAP“ und für die aktuelle Zeit sind keine ASAP-ServiceHours verfügbar.
- Es liegt eine Notfallschließung vor oder der Dienst
isDisabledist "true".
UNAVAILABLE_SLOT Die Bestellung im Voraus kann nicht ausgeführt werden. NO_CAPACITY Das Restaurant ist voll und es werden momentan keine Bestellungen angenommen. OUT_OF_SERVICE_AREA Die Bestellung kann nicht an die Adresse des Nutzers geliefert werden. Ein Beispiel finden Sie unter Validierung der Lieferadresse. NO_COURIER_AVAILABLE Die Bestellung kann aufgrund des begrenzten Lieferpersonals nicht geliefert werden.
Warenkorb validieren und Preis festlegen
Schlage jeden Einkaufswagen nach.
lineItemsund validiere ihn mit den aktuellen Daten in deinem System oder im System des Händlers. Der Wert MenuItemOffer.skuaus der Feedentität ist als LineItem enthalten.offerIdErstellen Sie bei Bedarf für jede Werbebuchung einen FoodOrderError. Erstellen Sie maximal einen Fehler für jedes Element. Geben Sie bei Bedarf die folgenden Fehlertypen zurück:Fehlertyp Anwendungsfall Wiederherstellbar INVALID Die Artikeldaten oder einige Optionsdaten sind ungültig. Nein NOT_FOUND Das Element oder eine der Optionen wurde nicht gefunden. Nein PRICE_CHANGED Der Preis eines Artikels oder einer Add-on-Kombination hat sich geändert. Dieser Fehler kann als behebbar behandelt werden. Ja AVAILABILITY_CHANGED Der für die Werbebuchungen angeforderte Betrag oder eine der Optionen ist nicht verfügbar. Ja REQUIREMENTS_NOT_MET Die Mindest- oder Höchstbestellmenge wurde nicht erreicht. Prüfen Sie dazu, ob der Preis im Einkaufswagen unter der Gebühr eligibleTransactionVolumeMinoder über der Gebühr liegt.eligibleTransactionVolumeMax. Weitere Informationen finden Sie im Beispiel zur Validierung des Mindestbestellwerts.Nein Gibt die validierte Liste der Werbebuchungen mit dem LineItemType
REGULARzurück. Die Summe aller Preise für Einkaufswagenpositionen ist der Einkaufswagenpreis oderSUBTOTAL.
Beispiele finden Sie unter Validierung von Warenkorbartikeln.
Servicegebühren berechnen
- Suchen Sie die richtige Fee-Entität für den Dienst anhand von
eligibleRegion,validFrom,validThroughundpriority. - Berechnen Sie den Gebührenbetrag basierend darauf, ob die Entität mit einer
price-,percentageOfCart- oderpricePerMeter-Property definiert wurde. - Geben Sie die Servicegebühr für den Lieferservice oder den Datenexport als LineItem mit dem LineItemType
DELIVERYbzw.FEEzurück. Füge die Gebühr der Liste Einkaufswagen.otherItemshinzu.
Werbeaktionen anwenden
- Suchen Sie die Entität Deal, indem Sie den Wert von Promotion.
couponmit dem Deal übereinstimmt.dealCode Validieren Sie den Deal und geben Sie bei Bedarf einen FoodOrderError zurück. Diese Fehler können als behebbar behandelt werden. Geben Sie bei Bedarf die folgenden Fehlertypen zurück:
Fehlertyp Anwendungsfall PROMO_NOT_RECOGNIZED Der Gutscheincode wurde nicht erkannt. PROMO_EXPIRED Die Gültigkeit des Angebots ist abgelaufen. PROMO_ORDER_INELIGIBLE Die Bestellung kommt nicht für den Gutschein infrage. PROMO_NOT_APPLICABLE Sonstige Gründe. Berechnen Sie den Betrag des Deals auf der Grundlage von Deal.
discountoder Deal.discountPercentageWenden Sie den Dealpreis anhand des Gesamtwerts des Einkaufswagens oder der Gesamtgebühr je nach Deal an.
dealTypeGeben Sie den Einkaufswagen.
promotionsmit angewendetem Angebot zurück.Geben Sie das Angebot als LineItem mit dem LineItemType
DISCOUNTzurück. Füge den Rabatt mit einem negativen Preis zur Liste Einkaufswagen.otherItemshinzu.
Antwort zurückgeben
- Erstellen Sie die ProposedOrder.
cart. Wenn während der Validierung keine Fehler festgestellt werden, ist der Antworteinkaufswagen mit dem Anfrageeinkaufswagen identisch. - Geben Sie die Liste ProposedOrder.
otherItemszurück, einschließlich Steuern, Gebühren, Trinkgeld und Rabatt (falls zutreffend). Weitere Informationen zur Konfiguration des Trinkgelds finden Sie unter Gratuity. - Füge den ProposedOrder.
totalPricehinzu, indem du den Preis, die Gebühren, den Rabatt, die Steuern und das Trinkgeld im Einkaufswagen hinzufügst. - Geben Sie FoodOrderExtension.
availableFulfillmentOptionsmit der entsprechenden FulfillmentOption zurück. Aktualisieren Sie die voraussichtliche Abhol- oder Lieferzeit auf die erwartete Zeit. - Wenn bei den vorherigen Validierungsprüfungen „FoodOrderErrors“ generiert wurde:
- Füge StructuredResponse.
errorund die Liste der Fehler in FoodErrorExtension.foodOrderErrorsein. - Geben Sie den ProposedOrder im Feld
correctedProposedOrderzurück, wenn alle Fehler behoben werden können. - Geben Sie PaymentOptions im Feld
paymentOptionszurück, wenn alle Fehler behoben werden können. - Fügen Sie optional
additionalPaymentOptionshinzu, wenn andere Zahlungsoptionen verfügbar sind und alle Fehler behoben werden können.
- Füge StructuredResponse.
- Wenn keine Validierungsfehler vorhanden sind, geben Sie
proposedOrderundpaymentOptionsim CheckoutResponse-Objekt zurück. Fügen Sie optionaladditionalPaymentOptionshinzu, wenn andere Zahlungsoptionen verfügbar sind.