Creare transazioni fisiche con Google Pay

Questa guida ti accompagnerà nel processo di sviluppo di un progetto Actions che incorpora transazioni per prodotti fisici e utilizza Google Pay per il pagamento.

Flusso delle transazioni

Quando il progetto Actions gestisce le transazioni fisiche tramite i pagamenti gestiti dal commerciante, usa la seguente procedura:

  1. (Facoltativo) Raccogliere informazioni: in base alla natura della tua transazione, ti consigliamo di raccogliere le seguenti informazioni dall'utente all'inizio della conversazione:
      .
    1. Convalida i requisiti delle transazioni - All'inizio della conversazione, verificare che l'utente soddisfi i requisiti per effettuare una transazione, come poiché i dati di pagamento sono stati configurati correttamente e disponibili prima mentre costruiscono il carrello.
    2. Richiedi un indirizzo di consegna: se la transazione richiede una consegna raccogline uno dall'utente.
  2. Crea l'ordine: guida l'utente attraverso una "assemblaggio carrello" dove scelgono quali articoli acquistare.
  3. Proporre l'ordine. Una volta completato il carrello, proponi l'ordine a l'utente, in modo che possa verificare che sia corretto. Se l'ordine viene confermato, ricevere una risposta con i dettagli dell'ordine e un token di pagamento.
  4. Finalizzare l'ordine e inviare una ricevuta: dopo aver confermato l'ordine, aggiorna il monitoraggio dell'inventario o altri servizi di evasione degli ordini e poi inviare una ricevuta all'utente.
  5. Inviare gli aggiornamenti sull'ordine: nel corso del ciclo di vita dell'evasione dell'ordine, fornire all'utente aggiornamenti sugli ordini inviando richieste PATCH agli ordini tramite Google Cloud CLI o tramite l'API Compute Engine.
di Gemini Advanced.

Limitazioni e linee guida per la revisione

Tieni presente che alle Azioni con transazioni si applicano norme aggiuntive. it possono essere necessarie fino a sei settimane per esaminare le Azioni con transazioni, quindi durante la pianificazione delle pubblicazioni. Per semplificare la procedura di revisione, di rispettare norme e linee guida per le transazioni prima di inviare l'Azione per la revisione.

Puoi implementare Azioni che vendono beni fisici solo nei seguenti paesi:

Australia
Brasile
Canada
Indonesia
Giappone
Messico
Russia
Singapore
Thailandia
Turchia
Regno Unito
Stati Uniti

Crea il tuo progetto

Per esempi completi di conversazioni transazionali, visualizza le transazioni Node.js esempio.

Configurazione

Quando crei l'azione, devi specificare che desideri eseguire delle transazioni nella console Actions.

Per configurare il progetto e il completamento, segui questi passaggi:

  1. Crea un nuovo progetto o importane uno esistente.
  2. Vai a Esegui il deployment > Informazioni sulla directory.
  3. In Altre informazioni > Transazioni > seleziona la casella "Esegui le tue azioni" utilizzare l'API Transactions per eseguire transazioni di beni fisici?".

1. Raccogliere informazioni (facoltativo)

1a. (Facoltativo) Convalida i requisiti della transazione

Non appena l'utente ha indicato di voler effettuare un acquisto, devi verificare che sia in grado di eseguire una transazione. Ad esempio, se richiamata, l'Azione potrebbe chiedere: "Vuoi ordinare scarpe, o controllare il saldo dell'account?" Se l'utente dice "ordina scarpe", devi assicurarti che procedere e dare loro l'opportunità di correggere le impostazioni che gli impediscono di continuare con la transazione. Per farlo, devi passare a una che esegue un controllo dei requisiti delle transazioni.

Crea requisiti della transazione - Controlla scena
  1. Dalla scheda Scene, aggiungi una nuova scena con il nome TransactionRequirementsCheck.
  2. In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
  3. In Seleziona tipo, seleziona actions.type.TransactionRequirementsCheckResult come tipo di slot.
  4. Nel campo del nome dell'area, assegna all'area il nome TransactionRequirementsCheck.
  5. Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
  6. Fai clic su Salva.

Un controllo dei requisiti delle transazioni genererà uno dei seguenti risultati:

  • Se i requisiti sono soddisfatti, il parametro di sessione viene impostato con esito positivo e potrai procedere con la creazione dell'ordine dell'utente.
  • Se non è possibile soddisfare uno o più requisiti, viene impostato il parametro sessione con una condizione di errore. In questo caso, devi allontanare la conversazione dall'esperienza transazionale o terminare la conversazione.
    • Se gli errori che restituiscono questo stato possono essere corretti dall'utente, gli verrà chiesto di risolvere i problemi sul proprio dispositivo. Se conversazione in corso su una piattaforma di sola voce, un trasferimento verrà avviata sullo smartphone dell'utente.

Gestire il risultato del controllo dei requisiti delle transazioni

  1. Dalla scheda Scene, seleziona l'elemento appena creato TransactionRequirementsCheck scena.
  2. In Condizione, fai clic su + per aggiungere una nuova condizione.
  3. Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizione di operazione riuscita:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
    
  4. Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

  5. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente sono pronti a effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase physical goods.
    
  6. In Transizione seleziona un'altra scena, in modo che l'utente possa continuare conversazione e procedere con la transazione.

  7. Seleziona la condizione else if scene.slots.status == "FINAL".

  8. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente non sono in grado di effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: Transaction requirements check failed.
    
  9. In Transizione, seleziona Termina conversazione per terminare la conversazione se un utente non è in grado di effettuare transazioni.

Richiedi un indirizzo di consegna

Se la tua transazione richiede l'indirizzo di consegna dell'utente, devi richiederlo da parte dell'utente. Può essere utile per determinare il prezzo totale, luogo di consegna/ritiro o per garantire che l'utente si trovi all'interno della regione coperta dal servizio. Per farlo devi passare a una scena che chieda all'utente di l'indirizzo di consegna.

Crea scena dell'indirizzo di consegna

  1. Dalla scheda Scene, aggiungi una nuova scena con il nome DeliveryAddress.
  2. In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
  3. In Seleziona tipo, seleziona actions.type.DeliveryAddressValue come tipo di area.
  4. Nel campo del nome dell'area, assegna all'area il nome TransactionDeliveryAddress.
  5. Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
  6. Fai clic su Save (Salva).

Quando configuri lo slot, puoi fornire un valore reason che ti consenta di: far precedere da una stringa la richiesta dell'assistente di ottenere un indirizzo.L'impostazione predefinita la stringa del motivo è "per sapere dove inviare l'ordine". Pertanto, l'assistente potrebbe chiedere all'utente: "Per sapere dove inviare l'ordine, mi serve il tuo indirizzo di consegna".

  • Sulle piattaforme con uno schermo, l'utente sceglierà l'indirizzo da utilizzare per la transazione. Se non hanno già fornito un indirizzo, dovranno inserire un nuovo indirizzo.
  • Sulle piattaforme solo vocali, l'assistente chiederà all'utente l'autorizzazione per condividono l'indirizzo predefinito per la transazione. Se non l'ha fatto in precedenza la conversazione viene passata a un telefono per l'accesso.

Per gestire il risultato relativo all'indirizzo di consegna:

  1. Dalla scheda Scene, seleziona la scena DeliveryAddress appena creata.
  2. In Condizione, fai clic su + per aggiungere una nuova condizione.
  3. Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizione di operazione riuscita:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
    
  4. Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

  5. Attiva l'opzione Invia prompt e fornisci una richiesta semplice all'utente. che hai ricevuto l'indirizzo:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Great! Your order will be delivered to
                $session.params.TransactionDeliveryAddress.location.postalAddress.locality
                $session.params.TransactionDeliveryAddress.location.postalAddress.administrativeArea
                $session.params.TransactionDeliveryAddress.location.postalAddress.regionCode
                $session.params.TransactionDeliveryAddress.location.postalAddress.postalCode
    
  6. In Transizione, seleziona un'altra scena per consentire all'utente di continuare. la conversazione.

  7. Seleziona la condizione else if scene.slots.status == "FINAL".

  8. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente non sono in grado di effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: I failed to get your delivery address.
    
  9. In Transizione, seleziona Termina conversazione per terminarla. se un utente non è in grado di effettuare transazioni.

Crea l'ordine

Una volta ottenute le informazioni utente necessarie, devi creare un assemblaggio" esperienza che guida l'utente nella creazione di un ordine. Ogni azione avere un flusso di assemblaggio del carrello leggermente diverso in base alle proprie prodotto o servizio.

L'esperienza di assemblaggio del carrello più basilare prevede la scelta da parte dell'utente degli articoli da aggiungere in base al loro ordine, anche se puoi progettare la conversazione per semplificare un'esperienza utente positiva. Potresti creare un'esperienza di assemblaggio del carrello che permetta all'utente di riordinare l'acquisto più recente con una semplice domanda sì o no. Puoi anche presentare all'utente una scheda di un carosello o di un elenco dei principali elementi in primo piano. o "consigliato" elementi.

Ti consigliamo di utilizzare risposte per presentare le opzioni dell'utente. visivamente, ma anche progettare la conversazione in modo che l'utente possa costruire la propria usando solo la voce. Per alcune best practice ed esempi esperienze di assemblaggio del carrello di alta qualità, consulta Linee guida per la progettazione.

Creazione di un ordine

Durante la conversazione, dovrai raccogliere gli elementi che un utente vuole acquistare e poi creare un oggetto Order.

Il Order deve contenere almeno quanto segue:

  • buyerInfo: informazioni sull'utente che effettua l'acquisto.
  • transactionMerchant - Informazioni sul commerciante che ha agevolato l'ordine.
  • contents: i contenuti effettivi dell'ordine indicato come lineItems.
  • priceAttributes - Dettagli dei prezzi dell'ordine, incluso il totale costo dell'ordine comprensivo di sconti e tasse.
di Gemini Advanced.

Consulta il Order la documentazione di risposta per creare il tuo carrello. Tieni presente che potrebbe essere necessario includere campi diversi a seconda dell'ordine.

Il codice di esempio riportato di seguito mostra un ordine completo, inclusi i campi facoltativi:

const order = {
  createTime: '2019-09-24T18:00:00.877Z',
  lastUpdateTime: '2019-09-24T18:00:00.877Z',
  merchantOrderId: orderId, // A unique ID String for the order
  userVisibleOrderId: orderId,
  transactionMerchant: {
    id: 'http://www.example.com',
    name: 'Example Merchant',
  },
  contents: {
    lineItems: [
      {
        id: 'LINE_ITEM_ID',
        name: 'Pizza',
        description: 'A four cheese pizza.',
        priceAttributes: [
          {
            type: 'REGULAR',
            name: 'Item Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 8990000,
            },
            taxIncluded: true,
          },
          {
            type: 'TOTAL',
            name: 'Total Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 9990000,
            },
            taxIncluded: true,
          },
        ],
        notes: [
          'Extra cheese.',
        ],
        purchase: {
          quantity: 1,
          unitMeasure: {
            measure: 1,
            unit: 'POUND',
          },
          itemOptions: [
            {
              id: 'ITEM_OPTION_ID',
              name: 'Pepperoni',
              prices: [
                {
                  type: 'REGULAR',
                  state: 'ACTUAL',
                  name: 'Item Price',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
                {
                  type: 'TOTAL',
                  name: 'Total Price',
                  state: 'ACTUAL',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
              ],
              note: 'Extra pepperoni',
              quantity: 1,
              subOptions: [],
            },
          ],
        },
      },
    ],
  },
  buyerInfo: {
    email: 'janedoe@gmail.com',
    firstName: 'Jane',
    lastName: 'Doe',
    displayName: 'Jane Doe',
  },
  priceAttributes: [
    {
      type: 'SUBTOTAL',
      name: 'Subtotal',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 9990000,
      },
      taxIncluded: true,
    },
    {
      type: 'DELIVERY',
      name: 'Delivery',
      state: 'ACTUAL',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 2000000,
      },
      taxIncluded: true,
    },
    {
      type: 'TAX',
      name: 'Tax',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 3780000,
      },
      taxIncluded: true,
    },
    {
      type: 'TOTAL',
      name: 'Total Price',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 15770000,
      },
      taxIncluded: true,
    },
  ],
  followUpActions: [
    {
      type: 'VIEW_DETAILS',
      title: 'View details',
      openUrlAction: {
        url: 'http://example.com',
      },
    },
    {
      type: 'CALL',
      title: 'Call us',
      openUrlAction: {
        url: 'tel:+16501112222',
      },
    },
    {
      type: 'EMAIL',
      title: 'Email us',
      openUrlAction: {
        url: 'mailto:person@example.com',
      },
    },
  ],
  termsOfServiceUrl: 'http://www.example.com',
  note: 'Sale event',
  promotions: [
    {
      coupon: 'COUPON_CODE',
    },
  ],
  purchase: {
    status: 'CREATED',
    userVisibleStatusLabel: 'CREATED',
    type: 'FOOD',
    returnsInfo: {
      isReturnable: false,
      daysToReturn: 1,
      policyUrl: 'http://www.example.com',
    },
    fulfillmentInfo: {
      id: 'FULFILLMENT_SERVICE_ID',
      fulfillmentType: 'DELIVERY',
      expectedFulfillmentTime: {
        timeIso8601: '2019-09-25T18:00:00.877Z',
      },
      location: location,
      price: {
        type: 'REGULAR',
        name: 'Delivery Price',
        state: 'ACTUAL',
        amount: {
          currencyCode: 'USD',
          amountInMicros: 2000000,
        },
        taxIncluded: true,
      },
      fulfillmentContact: {
        email: 'johnjohnson@gmail.com',
        firstName: 'John',
        lastName: 'Johnson',
        displayName: 'John Johnson',
      },
    },
    purchaseLocationType: 'ONLINE_PURCHASE',
  },
};

Crea opzioni per ordine e presentazione

Prima che l'utente confermi l'ordine, gli viene proposto scheda d'ordine. Puoi personalizzare il modo in cui questa scheda viene presentata all'utente: impostando diverse opzioni di ordine e presentazione.

Di seguito sono riportate le opzioni relative all'ordine e alla presentazione per effettuare un ordine che richiede Un indirizzo di consegna, incluso l'indirizzo email dell'utente riportato nella scheda di conferma dell'ordine:

const orderOptions = {
      'requestDeliveryAddress': true,
      'userInfoOptions': {
        'userInfoProperties': ['EMAIL']
      }
    };

const presentationOptions = {
      'actionDisplayName': 'PLACE_ORDER'
    };

Crea parametri di pagamento

L'oggetto paymentParameters includerà parametri di tokenizzazione che variano a seconda del responsabile di Google Pay che intendi utilizzare (come Stripe, Braintree, ACI ecc.).

const paymentParamenters = {
      'googlePaymentOption': {
        // facilitationSpec is expected to be a serialized JSON string
        'facilitationSpec': JSON.stringify({
          'apiVersion': 2,
          'apiVersionMinor': 0,
          'merchantInfo': {
            'merchantName': 'Example Merchant',
          },
          'allowedPaymentMethods': [
            {
              'type': 'CARD',
              'parameters': {
                'allowedAuthMethods': ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
                'allowedCardNetworks': [
                  'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'],
              },
              'tokenizationSpecification': {
                'type': 'PAYMENT_GATEWAY',
                'parameters': {
                  'gateway': 'example',
                  'gatewayMerchantId': 'exampleGatewayMerchantId',
                },
              },
            },
          ],
          'transactionInfo': {
            'totalPriceStatus': 'FINAL',
            'totalPrice': '15.77',
            'currencyCode': 'USD',
          },
        }),
      },
    };

I contenuti dell'oggetto tokenizationSpecification saranno diversi per ogni gateway di pagamento. La tabella seguente mostra i parametri utilizzati da ciascun gateway:

ESEMPIO
di Gemini Advanced.
"parameters": {
  "gateway": "example",
  "gatewayMerchantId": "exampleGatewayMerchantId"
}
ACI
di Gemini Advanced.
"parameters": {
  "gateway": "aciworldwide",
  "gatewayMerchantId": "YOUR_ENTITY_ID"
}
ADYEN
di Gemini Advanced.
"parameters": {
  "gateway": "adyen",
  "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"
}
ALFA-BANK
di Gemini Advanced.
"parameters": {
  "gateway": "alfabank",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BLUE_MEDIA
di Gemini Advanced.
"parameters": {
  "gateway": "bluemedia",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BLUESNAP
di Gemini Advanced.
"parameters": {
  "gateway": "bluesnap",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BRAINTREE
di Gemini Advanced.
"parameters": {
  "gateway": "braintree",
  "braintree:apiVersion": "v1",
  "braintree:sdkVersion": braintree.client.VERSION,
  "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID",
  "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY"
}
CHASE_PAYMENTECH
di Gemini Advanced.
"parameters": {
  "gateway": "chase",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER"
}
PAGAMENTO
di Gemini Advanced.
"parameters": {
  "gateway": "checkoutltd",
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"
}
CLOUDPAYMENTS
di Gemini Advanced.
"parameters": {
  "gateway": "cloudpayments",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
CYBERSOURCE
di Gemini Advanced.
"parameters": {
  "gateway": "cybersource",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
DATATRANS
di Gemini Advanced.
"parameters": {
  "gateway": "datatrans",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
EBANX
di Gemini Advanced.
"parameters": {
  "gateway": "ebanx",
  "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"
}
FIRST_DATA
di Gemini Advanced.
"parameters": {
  "gateway": "firstdata",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
GLOBAL_PAYMENTS
di Gemini Advanced.
"parameters": {
  "gateway": "globalpayments",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
GOPAY
di Gemini Advanced.
"parameters": {
  "gateway": "gopay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
HITRUST
di Gemini Advanced.
"parameters": {
  "gateway": "hitrustpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
IMSOLUZIONI
di Gemini Advanced.
"parameters": {
  "gateway": "imsolutions",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
LYRA
di Gemini Advanced.
"parameters": {
  "gateway": "lyra",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
MPGS
di Gemini Advanced.
"parameters": {
  "gateway": "mpgs",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
MONEY_MAIL_RU
di Gemini Advanced.
"parameters": {
  "gateway": "moneymailru",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NEWEBPAY
di Gemini Advanced.
"parameters": {
  "gateway": "newebpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NEXI
di Gemini Advanced.
"parameters": {
  "gateway": "nexi",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NMI
di Gemini Advanced.
"parameters": {
  "gateway": "creditcall",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYSAFE
di Gemini Advanced.
"parameters": {
  "gateway": "paysafe",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAGAMENTO
di Gemini Advanced.
"parameters": {
  "gateway": "payture",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYU
di Gemini Advanced.
"parameters": {
  "gateway": "payu",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PRZELEWY24
di Gemini Advanced.
"parameters": {
  "gateway": "przelewy24",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
RBKmoney
di Gemini Advanced.
"parameters": {
  "gateway": "rbkmoney",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
SBERBANK
di Gemini Advanced.
"parameters": {
  "gateway": "sberbank",
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
}
QUADRO
di Gemini Advanced.
"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
Striscia
di Gemini Advanced.
"parameters": {
  "gateway": "stripe",
  "stripe:version": "2018-10-31",
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
}
TAPPAY
di Gemini Advanced.
"parameters": {
  "gateway": "tappay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
TINKOFF
di Gemini Advanced.
"parameters": {
  "gateway": "tinkoff",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
UNITELLER
di Gemini Advanced.
"parameters": {
  "gateway": "uniteller",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
VANTIV
di Gemini Advanced.
"parameters": {
  "gateway": "vantiv",
  "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID",
  "vantiv:merchantOrderId": "YOUR_ORDER_ID",
  "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID",
  "vantiv:merchantReportGroup": "*web"
}
WORLDPAY
di Gemini Advanced.
"parameters": {
  "gateway": "worldpay",
  "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"
}
YANDEX
"parameters": {
  "gateway": "yandexcheckout",
  "gatewayMerchantId": "YOUR_SHOP_ID"
}

Salva i dati dell'ordine nel parametro di sessione

Dal fulfillment, salva i dati dell'ordine in un parametro di sessione. L'ordine verrà usato in più scene della stessa sessione.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions,
    paymentParameters: paymentParameters
};

Proponi l'ordine

Dopo aver creato un ordine, devi presentarlo all'utente per confermarlo o rifiutarlo. Per farlo, devi passare a una scena che esegue una decisione relativa alla transazione.

Crea scena decisionale transazione

  1. Dalla scheda Scene, aggiungi una nuova scena con il nome TransactionDecision.
  2. In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
  3. In Seleziona tipo, seleziona actions.type.TransactionDecisionValue come tipo di slot.
  4. Nel campo del nome dell'area, assegna all'area il nome TransactionDecision.
  5. Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
  6. In Configura slot, seleziona Utilizza parametro di sessione dal menu a discesa.
  7. In Configura slot,inserisci il nome del parametro di sessione utilizzato per archiviare l'ordine nel campo di testo (ad es. $session.params.order).
  8. Fai clic su Save (Salva).

Nel tentativo di riempire uno slot TransactionDecisionValue, l'assistente avvia un'esperienza integrata in cui l'elemento Order che hai trasmesso viene visualizzato direttamente una "scheda di anteprima del carrello". L'utente può dire "emetti ordine", rifiuta la transazione modificare un'opzione di pagamento, come la carta di credito o l'indirizzo, o richiedere una modifica i contenuti dell'ordine.

A questo punto l'utente può anche richiedere modifiche all'ordine. In questo caso, assicurati che l'evasione degli ordini possa gestire le richieste di modifica dell'ordine dopo per completare l'esperienza di assemblaggio del carrello.

Gestire il risultato della decisione sulle transazioni

Quando uno slot TransactionDecisionValue viene riempito, la risposta dell'utente alla verrà archiviata in un parametro di sessione. Questo valore contiene le seguenti:

  • ORDER_ACCEPTED,
  • ORDER_REJECTED,
  • DELIVERY_ADDRESS_UPDATED,
  • CART_CHANGE_REQUESTED
  • USER_CANNOT_TRANSACT.

Per gestire il risultato di una decisione relativa a una transazione:

  1. Dalla scheda Scene, seleziona la scena TransactionDecision appena creata.
  2. In Condizione, fai clic su + per aggiungere una nuova condizione.
  3. Nel campo di testo, inserisci la seguente sintassi per verificare la condizione di esito positivo:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  4. Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

  5. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente l'ordine è stato completato:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction completed! Your order
                $session.params.TransactionDecision.order.merchantOrderId is all
                set!
    
  6. In Transizione, seleziona Termina conversazione per terminarla.

  7. In Condizione, fai clic su + per aggiungere una nuova condizione.

  8. Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizioni di errore:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
    
  9. Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

  10. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente l'ordine è stato rifiutato:

    candidates:
      - first_simple:
          variants:
            - speech: Look like you don't want to order anything. Goodbye.
    
  11. In Transizione seleziona Termina conversazione per terminarla.

  12. Seleziona la condizione else if scene.slots.status == "FINAL".

  13. Attiva l'opzione Invia prompt e fornisci una richiesta semplice all'utente. sapere di non essere in grado di effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction failed with status
                $session.params.TransactionDecision.transactionDecision
    
  14. In Transizione, seleziona Termina conversazione per terminarla. se un utente non è in grado di effettuare transazioni.

Finalizza l'ordine e invia una ricevuta

Quando l'area TransactionDecisionValue restituisce il risultato ORDER_ACCEPTED, devi eseguire immediatamente l'elaborazione richiesta per "confermare" il dell'ordine (ad esempio, rimanendo nel tuo database e addebitando un costo all'utente).

Puoi terminare la conversazione con questa risposta, ma devi includere una semplice per mantenere viva la conversazione. Se fornisci questo indirizzo iniziale orderUpdate, l'utente vedrà una "scheda con ricevuta compressa" insieme agli altri della tua risposta. Questa scheda rispecchierà la ricevuta che l'utente trova nel suo Cronologia ordini.

Durante la conferma dell'ordine, l'oggetto dell'ordine può includere userVisibleOrderId, che è l'ID che l'utente vede per l'ordine. Puoi riutilizzare i tuoi merchantOrderId per questo campo.

Parte dell'oggetto OrderUpdate dovrà contenere un oggetto azione di follow-up, che si manifestano come pulsanti dell'URL in fondo ai dettagli dell'ordine che l'utente che puoi trovare nella Cronologia ordini dell'assistente.

  • Devi fornire, come minimo, un VIEW_DETAILS un'azione aggiuntiva per ogni ordine. Deve contenere un link diretto rappresentazione dell'ordine sulla tua app mobile o sul tuo sito web.
  • Devi anche inviare una ricevuta via email formale che soddisfi tutti i requisiti legali. i requisiti per effettuare una transazione, oltre alla scheda della ricevuta. nella conversazione dell'Azione.

Per inviare un aggiornamento iniziale dell'ordine:

  1. Dalla scheda Scene, seleziona la tua TransactionDecision scena.
  2. In Condizione, seleziona la condizione che verifica il risultato con esito positivo. ORDER_ACCEPTED:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  3. Per questa condizione, attiva Chiama il webhook e fornisci un intent nome del gestore, ad esempio update_order.

  4. Nel codice webhook, aggiungi un gestore di intent per l'invio di un ordine iniziale aggiornamento:

    app.handle('update_order', conv => {
      const currentTime = new Date().toISOString();
      let order = conv.session.params.TransactionDecision.order;
      conv.add(new OrderUpdate({
        'updateMask': {
          'paths': [
            'purchase.status',
            'purchase.user_visible_status_label'
          ]
        },
        'order': {
          'merchantOrderId': order.merchantOrderId,
          'lastUpdateTime': currentTime,
          'purchase': {
            'status': 'CONFIRMED',
            'userVisibleStatusLabel': 'Order confirmed'
          },
        },
        'reason': 'Reason string
      }));
    });
    

Invia aggiornamenti sull'ordine

Dovrai informare l'utente dello stato dell'ordine nel corso di e la sua durata. Invia gli aggiornamenti dell'ordine dell'utente inviando HTTP Richieste PATCH all'API Orders con lo stato e i dettagli dell'ordine.

Configura richieste asincrone all'API Orders

Le richieste di aggiornamento degli ordini all'API Orders sono autorizzate da un accesso di accesso. Per eseguire il PATCH di un aggiornamento dell'ordine all'API Orders, scarica un file JSON chiave dell'account di servizio associata al progetto Actions Console, quindi la chiave dell'account di servizio per un token di connessione che può essere passato Intestazione Authorization della richiesta HTTP.

Per recuperare la chiave dell'account di servizio, segui questi passaggi:

  1. Nella console Google Cloud, Vai a Menu SFTP > API e Servizi > Credenziali > Crea le credenziali > Chiave account di servizio.
  2. In Account di servizio, seleziona Nuovo account di servizio.
  3. Imposta l'account di servizio su service-account.
  4. Imposta Ruolo su Progetto > Proprietario.
  5. Imposta il tipo di chiave su JSON.
  6. Seleziona Crea.
  7. Una chiave dell'account di servizio JSON privata verrà scaricata sulla macchina locale.

Nel codice di aggiornamento dell'ordine, puoi scambiare la chiave di servizio con un token di connessione utilizzando la libreria client delle API di Google Ambito "https://www.googleapis.com/auth/actions.order.developer". Puoi visualizzare passaggi di installazione ed esempi sulla libreria client API Pagina GitHub.

Puoi anche fare riferimento a order-update.js nel nostro Esempio di Node.js per un esempio di scambio di chiavi.

Invia aggiornamenti sull'ordine

Dopo aver scambiato la chiave dell'account di servizio con un token di connessione OAuth, può inviare aggiornamenti sugli ordini come richieste PATCH autorizzate all'API Orders.

URL dell'API Orders: PATCH https://actions.googleapis.com/v3/orders/${orderId}

Fornisci le seguenti intestazioni nella tua richiesta:

  • "Authorization: Bearer token" con il token di connessione OAuth con cui hai scambiato la chiave dell'account di servizio.
  • "Content-Type: application/json".

La richiesta PATCH deve avere un corpo JSON nel seguente formato:

{ "orderUpdate": OrderUpdate }

La OrderUpdate è costituito dai seguenti campi di primo livello:

  • updateMask. I campi dell'ordine che stai aggiornando. Per aggiornare lo stato dell'ordine, imposta il valore su purchase.status, purchase.userVisibleStatusLabel.
  • order: i contenuti dell'aggiornamento. Se stai aggiornando il contenuti dell'ordine, imposta il valore sull'oggetto Order aggiornato. Se stai aggiornando lo stato dell'ordine (ad es. da da "CONFIRMED" a "SHIPPED"), l'oggetto contiene seguenti campi:

    • merchantOrderId: lo stesso ID impostato nell'oggetto Order.
    • lastUpdateTime: il timestamp di questo aggiornamento.
    • purchase: un oggetto che contiene:
      • status: lo stato dell'ordine come PurchaseStatus, ad esempio "SHIPPED" o "DELIVERED".
      • userVisibleStatusLabel: un'etichetta rivolta agli utenti che fornisce dettagli su lo stato dell'ordine, ad esempio "L'ordine è stato spedito ed è modo".
  • userNotification (facoltativo) - A userNotification che può essere visualizzato sul dispositivo dell'utente quando viene inviato questo aggiornamento. Nota che l'inclusione di questo oggetto non garantisce la visualizzazione di dal dispositivo dell'utente.

Il seguente codice campione mostra un esempio OrderUpdate che aggiorna la stato dell'ordine a DELIVERED:

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = require('./service-account.json')

// Create a new JWT client for the Actions API using credentials
// from the service account key.
let jwtClient = new google.auth.JWT(
    serviceAccountKey.client_email,
    null,
    serviceAccountKey.private_key,
    ['https://www.googleapis.com/auth/actions.order.developer'],
    null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare order update
const orderUpdate = new OrderUpdate({
    updateMask: {
      paths: [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    order: {
      merchantOrderId: orderId, // Specify the ID of the order to update
      lastUpdateTime: new Date().toISOString(),
      purchase: {
        status: 'DELIVERED',
        userVisibleStatusLabel: 'Order delivered',
      },
    },
    reason: 'Order status updated to delivered.',
});

// Set up the PATCH request header and body,
// including the authorized token and order update.
let options = {
  method: 'PATCH',
  uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
  auth: {
    bearer: tokens.access_token,
  },
  body: {
    header: {
      isInSandbox: true,
    },
    orderUpdate,
  },
  json: true,
};

// Send the PATCH request to the Orders API.
try {
  await request(options);
} catch (e) {
  console.log(`Error: ${e}`);
}
Impostare lo stato dell'acquisto

Aggiornamento di un ordine: status deve descrivere lo stato attuale dell'ordine. Nel tuo aggiornamento (order.purchase.status) utilizza uno dei seguenti valori:

  • CREATED - L'ordine è stato accettato dall'utente e "creato" dal punto di vista dell'azione, ma richiede l'elaborazione manuale sul backend.
  • CONFIRMED - L'ordine è attivo e in fase di elaborazione per l'evasione.
  • IN_PREPARATION - L'ordine è in fase di preparazione per la spedizione/consegna, ad esempio il cibo in fase di preparazione o di confezionamento.
  • READY_FOR_PICKUP: l'ordine è disponibile per il ritiro da parte del destinatario.
  • DELIVERED - L'ordine è stato consegnato al destinatario
  • OUT_OF_STOCK: uno o più articoli dell'ordine non sono disponibili.
  • CHANGE_REQUESTED - L'utente ha richiesto una modifica all'ordine e la modifica è in fase di elaborazione.
  • RETURNED - L'ordine è stato restituito dall'utente dopo la consegna.
  • REJECTED - Se non sei stato in grado di elaborare, addebitare o altrimenti "attivare" l'ordine.
  • CANCELLED - L'ordine è stato annullato dall'utente.

Devi inviare aggiornamenti sull'ordine per ogni stato pertinente per il tuo transazione. Ad esempio, se la transazione richiede l'elaborazione manuale registra l'ordine dopo averlo effettuato, invia un aggiornamento dell'ordine CREATED fino l'ulteriore elaborazione viene eseguita. Non tutti gli ordini richiedono ogni valore dello stato.

Testa il progetto

Durante il test del progetto, puoi abilitare la modalità sandbox nella console di Actions per testare l'Azione senza addebitare l'importo su un metodo di pagamento. Per attivare la modalità sandbox:

  1. Nella console di Actions, fai clic su Test nel menu di navigazione.
  2. Fai clic su Impostazioni.
  3. Attiva l'opzione Sandbox per lo sviluppo.

Per le transazioni fisiche, puoi anche impostare il campo isInSandbox su true in del campione. Questa azione equivale ad attivare l'impostazione della modalità sandbox in la console Actions. Per visualizzare uno snippet di codice che utilizza isInSandbox, consulta le Sezione Inviare aggiornamenti sull'ordine.

Risoluzione dei problemi

Se riscontri problemi durante i test, ti invitiamo a leggere la nostra procedura per la risoluzione dei problemi. per le transazioni.