La procedura di pagamento viene attivata quando un utente crea un carrello. I contenuti del carrello dell'utente e i dettagli dell'ordine vengono inviati al servizio web end-to-end di ordinazione. Queste informazioni vengono convalidate dal tuo servizio web, quindi puoi procedere o apportare modifiche al carrello in base alle tue esigenze.
Il gestore dei pagamenti per il tuo servizio web deve rispondere alle richieste POST. Quando un cliente sceglie di effettuare il pagamento, Google invia al servizio web end-to-end degli ordini un corpo della richiesta JSON sotto forma di CheckoutRequestMessage, che contiene i dettagli del Cart di un cliente. Il tuo servizio web risponde quindi con un
CheckoutResponseMessage. Il seguente diagramma illustra il processo.
Alla ricezione di una richiesta di pagamento, il servizio web end-to-end dell'ordine deve:
- Controlla la validità del carrello in base agli attuali prezzi degli articoli, alla disponibilità e al servizio del fornitore.
- Calcola il prezzo totale (inclusi eventuali sconti, tasse e commissioni di consegna).
- In caso di esito positivo, rispondi con un carrello non modificato.
- Se l'operazione non va a buon fine, rispondi con un messaggio di errore e con un nuovo ordine proposto.
Prima di iniziare a implementare il pagamento, ti consigliamo di consultare la documentazione della panoramica sull'evasione degli ordini.
Messaggio di richiesta pagamento
Per convalidare il carrello del cliente, quando un cliente sceglie di effettuare il pagamento, Google invia una richiesta al tuo servizio web con un corpo JSON sotto forma di CheckoutRequestMessage. L'ordine del cliente viene inviato solo in seguito nel flusso end-to-end dell'ordine.
I dati contenuti in un
CheckoutRequestMessage
includono quanto segue:
- Intento: il campo
inputs[0].intentdel corpo di ogni richiesta di pagamento contiene il valore della stringaactions.foodordering.intent.CHECKOUT. - Carrello: il campo
inputs[0].arguments[0].extensiondi una richiesta di pagamento contiene un oggettoCartche rappresenta il carrello del cliente. - Consegna o estrazione: il campo dell'estensione dell'oggetto
Cartcontiene un oggettoFoodCartExtensionche specifica le proprietà per la consegna o l'estrazione:- Per gli ordini con consegna, l'oggetto
FoodCartExtensioninclude l'indirizzo di consegna. - Per gli ordini con ritiro o asporto, l'oggetto
FoodCartExtensionnon contiene informazioni sulla posizione.
- Per gli ordini con consegna, l'oggetto
- Sandbox: il campo
isInSandboxdi una richiesta di pagamento contiene un valore booleano che indica se la transazione utilizza pagamenti sandbox.
Esempio di richiesta di pagamento
Di seguito è riportato un esempio di 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
}
Messaggio di risposta al pagamento
Dopo aver ricevuto una richiesta dal servizio end-to-end di ordinazione, il servizio web di pagamento
deve elaborarla e rispondere con un CheckoutResponseMessage. CheckoutResponseMessage deve coprire una richiesta andata a buon fine o non riuscita.
Richiesta riuscita
Se una richiesta di pagamento ha esito positivo, CheckoutResponseMessage deve includere
ProposedOrder
e
PaymentOptions:
ProposedOrdercart: un oggettocartidentico al carrello fornito inCheckoutRequestMessage. Se è necessario modificare i contenuti del carrello, ilCheckoutResponseMessagedeve includere invece unFoodErrorExtensioncon unProposedOrdercorretto.otherItems: articoli aggiunti dal fornitore, ad esempio spese di consegna, tasse e altre commissioni. Possono anche contenere mance aggiunte dall'utente.totalPrice: il prezzo totale dell'ordine.extension: unFoodOrderExtensionche definisce le informazioni di evasione dell'ordine, come i tempi di consegna.
PaymentOptions- La configurazione dell'elaborazione dei pagamenti verrà trattata più avanti in Configurare Google
Pay.
Puoi utilizzare JSON segnaposto in
CheckoutResponseMessagefinché non è tutto pronto per implementare l'elaborazione dei pagamenti. - Per aggiungere opzioni di pagamento segnaposto in
CheckoutResponseMessage, consulta l'esempio riportato di seguito, che utilizza un gateway di pagamento di esempio perPaymentOptions.
- La configurazione dell'elaborazione dei pagamenti verrà trattata più avanti in Configurare Google
Pay.
Puoi utilizzare JSON segnaposto in
Esempio di risposta riuscita
{
"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": []
}
}
}
]
}
}
}
]
}
}
}
Richiesta non riuscita
Se una richiesta di pagamento non va a buon fine, CheckoutResponseMessage deve
includere FoodErrorExtension, che contiene un elenco di
FoodOrderError
elementi che descrivono gli eventuali errori che si sono verificati. Se si verificano errori recuperabili nell'ordine, come una variazione di prezzo di un articolo nel carrello, l'elemento FoodErrorExtension deve includere il correctedProposedOrder.
Esempio di risposta non riuscita
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"error": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
"foodOrderErrors": [
{
"error": "CLOSED",
"description": "The restaurant is closed."
}
]
}
}
}
]
}
}
}
Implementazione di Google Checkout
Quando implementi il pagamento, devi seguire questi passaggi.
Convalidare il servizio
Restituisci un valore FoodOrderError per la prima condizione di errore del servizio rilevata. Questi errori non sono recuperabili, quindi il primo errore riscontrato deve essere restituito. Per una descrizione degli errori recuperabili, consulta Gestione degli errori.
- Leggi la proprietà FulfillmentOptionInfo nella richiesta per determinare se il tipo di evasione è per
deliveryopickup. Se necessario, restituisci i seguenti tipi di errore:
Tipo di errore Caso d'uso INVALID Il tipo di evasione non è valido. NOT_FOUND Il tipo di evasione non è stato trovato. CHIUSO - Non sono presenti finestre OperationHours per l'ordine.
- L'ordine è di tipo "Appena possibile" e non sono disponibili ServiceHours il prima possibile per l'ora attuale.
- C'è una chiusura di emergenza o il servizio
isDisabledè attivo.
UNAVAILABLE_SLOT Impossibile completare l'ordine in anticipo. NO_CAPACITY Il ristorante è affollato e non accetta ordini al momento. OUT_OF_SERVICE_AREA L'ordine non può essere consegnato all'indirizzo dell'utente. Per un esempio, consulta la sezione Convalida dell'indirizzo di consegna. NO_COURIER_AVAILABLE L'ordine non può essere consegnato a causa del personale limitato addetto alla consegna.
Convalidare e impostare il prezzo del carrello
Cerca ogni carrello.
lineItemsed esegui la convalida con i dati attuali nel tuo sistema o nel sistema del commerciante. Il valore MenuItemOffer.skudell'entità del feed è incluso come LineItem.offerId. Crea un valore FoodOrderError per ogni elemento pubblicitario, se necessario. Crea un massimo di un errore per ogni articolo. Se necessario, restituisci i seguenti tipi di errore:Tipo di errore Caso d'uso Recuperabile INVALID I dati dell'articolo o i dati delle opzioni non sono validi. No NOT_FOUND Impossibile trovare l'elemento o una delle opzioni. No PRICE_CHANGED Il prezzo di una combinazione di articoli o componenti aggiuntivi è cambiato. Questo errore può essere considerato recuperabile. Sì AVAILABILITY_CHANGED L'importo richiesto per gli elementi pubblicitari o una qualsiasi delle opzioni non è disponibile. Sì REQUIREMENTS_NOT_MET Il valore minimo o massimo dell'ordine non è stato soddisfatto. Per determinarlo, controlla se il prezzo del carrello è inferiore alla Tariffa. eligibleTransactionVolumeMino superiore alla Tariffa.eligibleTransactionVolumeMax. Vedi l'esempio nella convalida del valore minimo dell'ordine.No Restituisci l'elenco convalidato di elementi pubblicitari con LineItemType
REGULAR. La somma di tutti i prezzi degli articoli pubblicitari del carrello corrisponde al prezzo del carrello oSUBTOTAL.
Guarda gli esempi relativi alla convalida degli articoli del carrello.
Calcolare le commissioni di servizio
- Trova l'entità Fee corretta per il servizio in base a
eligibleRegion,validFrom,validThroughepriority. - Calcola l'importo della tariffa se l'entità è stata definita con una proprietà
price,percentageOfCartopricePerMeter. - Restituisci la commissione di servizio di consegna o estrazione come LineItem con
LineItemType rispettivamente
DELIVERYoFEE. Aggiungi la tariffa all'elenco Carrello.otherItems.
Applica promozioni
- Trova l'entità Deal in base alla corrispondenza tra il valore di Promozione.
coupone il valore Deal.dealCode. Convalida il deal e restituisci un FoodOrderError, se necessario. Questi errori possono essere trattati come recuperabili. Se necessario, restituisci i seguenti tipi di errore:
Tipo di errore Caso d'uso PROMO_NOT_RECOGNIZED Codice coupon non riconosciuto. PROMO_EXPIRED La validità del deal è scaduta. PROMO_ORDER_INELIGIBLE L'ordine non è idoneo per il coupon. PROMO_NOT_APPLICABLE Per qualsiasi altro motivo. Calcola l'importo del prezzo del deal in base al Deal
discounto Deal.discountPercentage.Applica l'importo del prezzo dell'offerta utilizzando il totale del carrello o il totale della tariffa in base all'accordo.
dealType.Restituisci il carrello.
promotionscon la promozione applicata.Restituisci la promozione come LineItem con LineItemType
DISCOUNT. Aggiungi lo sconto all'elenco Carrello.otherItemscon un prezzo negativo.
Restituire la risposta
- Crea il ProposedOrder.
cart, il carrello delle risposte è uguale al carrello delle richieste se non vengono riscontrati errori durante la convalida. - Restituisci l'elenco ProposedOrder.
otherItemsche include tasse, commissioni, mance e sconto, se applicati. Consulta Gratuity per ulteriori dettagli su come configurare l'elemento senza costi. - Includi l'ProposedOrder.
totalPriceaggiungendo il prezzo del carrello, le commissioni, lo sconto, le tasse e la mancia. - Restituisci
FoodOrderExtension.
availableFulfillmentOptionscon la rispettiva FulfillmentOption. Aggiorna i tempi di ritiro o consegna stimati all'orario previsto. - Se sono stati generati errori FoodOrderError dai controlli di convalida precedenti:
- Includi StructuredResponse.
errore l'elenco degli errori in FoodErrorExtension.foodOrderErrors. - Se tutti gli errori sono recuperabili, restituisci il valore ProposedOrder nel campo
correctedProposedOrder. - Restituisci PaymentOptions nel campo
paymentOptionsse tutti gli errori sono recuperabili. - (Facoltativo) Includi
additionalPaymentOptionsse sono disponibili altre opzioni di pagamento e se tutti gli errori sono recuperabili.
- Includi StructuredResponse.
- Se non sono presenti errori di convalida, restituisci
proposedOrder,paymentOptionsnell'oggetto CheckoutResponse. Se vuoi, includiadditionalPaymentOptionsse sono disponibili altre opzioni di pagamento.