Mit Google Pay physische Transaktionen durchführen

In diesem Leitfaden wird die Entwicklung eines Actions-Projekts beschrieben, das Transaktionen für physische Waren umfasst und Google Pay für Zahlungen verwendet.

Transaktionsablauf

Wenn in Ihrem Actions-Projekt physische Transaktionen mit vom Händler verwalteten Zahlungen verarbeitet werden, wird der folgende Ablauf verwendet:

  1. Informationen erfassen (optional): Je nach Art der Transaktion möchten Sie möglicherweise zu Beginn der Unterhaltung die folgenden Informationen vom Nutzer einholen:
    1. Transaktionsanforderungen validieren: Überprüfen Sie zu Beginn der Unterhaltung, ob der Nutzer die Anforderungen für eine Transaktion erfüllt, z. B. ob die Zahlungsinformationen richtig konfiguriert und verfügbar sind, bevor Sie den Einkaufswagen erstellen.
    2. Lieferadresse anfordern: Wenn für die Transaktion eine Lieferadresse erforderlich ist, fordern Sie eine vom Nutzer an.
  2. Bestellung zusammenstellen: Gehe mit dem Nutzer durch einen „Wagenbau“, bei dem er die Artikel auswählt, die er kaufen möchte.
  3. Bestellung vorschlagen: Sobald der Einkaufswagen fertig ist, schlagen Sie dem Nutzer die Bestellung vor, damit er bestätigen kann, dass sie korrekt ist. Wenn die Bestellung bestätigt wird, erhalten Sie eine Antwort mit Bestelldetails und einem Zahlungstoken.
  4. Bestellung abschließen und Beleg senden: Wenn die Bestellung bestätigt ist, aktualisieren Sie die Inventarverfolgung oder andere Auftragsausführungsdienste und senden Sie dann eine Quittung an den Nutzer.
  5. Bestellaktualisierungen senden: Biete dem Nutzer während der Laufzeit der Bestellung Aktualisierungen an, indem du PATCH-Anfragen an die Orders API sendest.

Einschränkungen und Richtlinien für Überprüfungen

Für Aktionen mit Transaktionen gelten zusätzliche Richtlinien. Die Überprüfung von Aktionen mit Transaktionen kann bis zu sechs Wochen dauern. Berücksichtigen Sie diese Zeit daher bei der Planung Ihres Release-Zeitplans. Achte darauf, dass du die Richtlinien für Transaktionen einhältst, bevor du deine Aktion zur Überprüfung einreichst, um den Überprüfungsprozess zu vereinfachen.

Du kannst Aktionen für physische Waren nur in den folgenden Ländern implementieren:

Australien
Brasilien
Kanada
Indonesien
Japan
Mexiko
Russland
Singapur
Thailand
Türkei
Vereinigtes Königreich
USA

Ihr Projekt erstellen

Ausführliche Beispiele für transaktionale Unterhaltungen finden Sie im Node.js-Transaktionsbeispiel.

Einrichtung

Beim Erstellen einer Aktion müssen Sie in der Actions Console angeben, dass Sie Transaktionen ausführen möchten.

So richten Sie Ihr Projekt und die Auftragsausführung ein:

  1. Erstellen Sie ein neues Projekt oder importieren Sie ein vorhandenes Projekt.
  2. Gehen Sie zu Bereitstellen > Verzeichnisinformationen.
  3. Klicke unter Zusätzliche Informationen > Transaktionen auf das Kästchen neben "Verwenden deine Aktionen die Transactions API, um Transaktionen mit physischen Waren durchzuführen?".

1. Informationen erfassen (optional)

1a. Transaktionsanforderungen validieren (optional)

Sobald der Nutzer angegeben hat, dass er etwas kaufen möchte, solltest du prüfen, ob er eine Transaktion ausführen kann. Wenn deine Aktion aufgerufen wird, könnte sie beispielsweise fragen: "Möchtest du Schuhe bestellen oder deinen Kontostand überprüfen?" Wenn der Nutzer „Schuhe bestellen“ sagt, solltest du dafür sorgen, dass er fortfahren kann und ihm die Möglichkeit geben, alle Einstellungen zu korrigieren, die ihn daran hindern, die Transaktion fortzusetzen. Wechseln Sie dazu zu einer Szene, in der eine Prüfung der Transaktionsanforderungen durchgeführt wird.

Prüfung der Transaktionsanforderungen erstellen
  1. Fügen Sie auf dem Tab „Szenen“ eine neue Szene mit dem Namen TransactionRequirementsCheck hinzu.
  2. Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
  3. Wählen Sie unter Typ auswählen actions.type.TransactionRequirementsCheckResult als Slottyp aus.
  4. Geben Sie der Anzeigenfläche den Namen TransactionRequirementsCheck im Feld für den Slotnamen.
  5. Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
  6. Klicken Sie auf Speichern.

Die Prüfung der Transaktionsanforderungen führt zu einem der folgenden Ergebnisse:

  • Wenn die Anforderungen erfüllt sind, wird der Sitzungsparameter mit einer Erfolgsbedingung festgelegt und Sie können mit der Erstellung des Auftrags des Nutzers fortfahren.
  • Wenn eine oder mehrere Anforderungen nicht erfüllt werden können, wird der Sitzungsparameter mit einer Fehlerbedingung festgelegt. In diesem Fall sollten Sie die Unterhaltung von der Transaktionserfahrung wegschwenken oder die Unterhaltung beenden.
    • Wenn Fehler, die zum Fehlerstatus führen, vom Nutzer behoben werden können, wird er aufgefordert, diese Probleme auf seinem Gerät zu beheben. Wenn die Unterhaltung auf einer sprachgesteuerten Oberfläche stattfindet, wird eine Übergabe an das Smartphone des Nutzers initiiert.

Ergebnis der Prüfung für Transaktionsanforderungen verarbeiten

  1. Wählen Sie auf dem Tab Szenen die neu erstellte Szene TransactionRequirementsCheck aus.
  2. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
  3. Geben Sie die folgende Bedingungssyntax in das Textfeld ein, um zu prüfen, ob die Erfolgsbedingung erfüllt ist:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
    
  4. Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor if scene.slots.status == "FINAL" zu platzieren.

  5. Aktivieren Sie Aufforderungen senden und geben Sie den Nutzer mit einer einfachen Aufforderung an, eine Transaktion vorzunehmen:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase physical goods.
    
  6. Wählen Sie unter Übergang eine andere Szene aus, damit der Nutzer die Unterhaltung fortsetzen und mit der Transaktion fortfahren kann.

  7. Wählen Sie die Bedingung else if scene.slots.status == "FINAL" aus.

  8. Aktivieren Sie Aufforderungen senden und blenden Sie eine einfache Aufforderung ein, die den Nutzer darüber informiert, dass eine Transaktion nicht möglich ist:

    candidates:
      - first_simple:
          variants:
            - speech: Transaction requirements check failed.
    
  9. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.

Lieferadresse anfordern

Wenn für Ihre Transaktion die Lieferadresse eines Nutzers erforderlich ist, sollten Sie diese beim Nutzer anfordern. Dies kann nützlich sein, um den Gesamtpreis und den Liefer-/Abholort zu ermitteln oder um sicherzustellen, dass sich der Nutzer in Ihrer Dienstleistungsregion befindet. Wechseln Sie dazu zu einer Szene, in der der Nutzer zur Eingabe seiner Lieferadresse aufgefordert wird.

Szene für Lieferadresse erstellen

  1. Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen DeliveryAddress hinzu.
  2. Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
  3. Wählen Sie unter Typ auswählen actions.type.DeliveryAddressValue als Slottyp aus.
  4. Geben Sie der Anzeigenfläche den Namen TransactionDeliveryAddress im Feld für den Slotnamen.
  5. Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
  6. Klicken Sie auf Speichern.

Beim Konfigurieren des Slots können Sie einen reason angeben, mit dem Sie die Anfrage von Assistant zum Abrufen einer Adresse mit einem String voranstellen können.Der Standardstring für den Grund ist „zu wissen, wohin die Bestellung gesendet werden soll“. Daher könnte Assistant den Nutzer fragen: "Um zu wissen, wohin ich die Bestellung schicken soll, brauche ich Ihre Lieferadresse."

  • Auf Oberflächen mit einem Bildschirm wählt der Nutzer aus, welche Adresse für die Transaktion verwendet werden soll. Wenn sie noch keine Adresse angegeben haben, können sie eine neue Adresse eingeben.
  • Auf Oberflächen mit Sprachfunktion fragt Assistant den Nutzer um die Berechtigung zur Freigabe seiner Standardadresse für die Transaktion. Wenn sie noch keine Adresse angegeben haben, wird das Gespräch zur Teilnahme an ein Telefon weitergeleitet.

So verarbeiten Sie das Ergebnis für die Lieferadresse:

  1. Wählen Sie auf dem Tab Szenen die neu erstellte Szene DeliveryAddress aus.
  2. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
  3. Geben Sie die folgende Bedingungssyntax in das Textfeld ein, um zu prüfen, ob die Erfolgsbedingung erfüllt ist:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
    
  4. Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor if scene.slots.status == "FINAL" zu platzieren.

  5. Aktivieren Sie Aufforderungen senden und zeigen Sie dem Nutzer durch eine einfache Aufforderung an, dass Sie seine Adresse erhalten haben:

    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. Wählen Sie unter Übergang eine andere Szene aus, damit der Nutzer die Unterhaltung fortsetzen kann.

  7. Wählen Sie die Bedingung else if scene.slots.status == "FINAL" aus.

  8. Aktivieren Sie Aufforderungen senden und blenden Sie eine einfache Aufforderung ein, die den Nutzer darüber informiert, dass eine Transaktion nicht möglich ist:

    candidates:
      - first_simple:
          variants:
            - speech: I failed to get your delivery address.
    
  9. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.

Auftrag erstellen

Sobald Sie die benötigten Nutzerinformationen haben, erstellen Sie einen „Einkaufswagenbau“, der den Nutzer beim Erstellen einer Bestellung anleitet. Jede Aktion hat je nach Produkt oder Dienstleistung einen etwas anderen Montageablauf für den Warenkorb.

Bei der einfachsten Montage eines Einkaufswagens wählt der Nutzer Artikel aus einer Liste aus, die er seiner Bestellung hinzufügt. Sie können die Unterhaltung jedoch so gestalten, dass die User Experience vereinfacht wird. Sie könnten einen Warenkorbbau erstellen, der es dem Nutzer ermöglicht, seinen letzten Einkauf über eine einfache Ja-oder-Nein-Frage noch einmal zu bestellen. Sie können dem Nutzer auch ein Karussell oder eine Listenkarte mit den beliebtesten oder empfohlenen Artikeln präsentieren.

Wir empfehlen, umfangreiche Antworten zu verwenden, um die Optionen des Nutzers visuell darzustellen, aber auch die Unterhaltung so zu gestalten, dass der Nutzer seinen Warenkorb nur mit seiner Stimme erstellen kann. Einige Best Practices und Beispiele für die qualitativ hochwertige Montage von Einkaufswagen finden Sie in den Designrichtlinien.

Auftrag erstellen

Während der Unterhaltung musst du die Artikel sammeln, die ein Nutzer kaufen möchte, und dann ein Order-Objekt erstellen.

Die Order muss mindestens Folgendes enthalten:

  • buyerInfo: Informationen zum Nutzer, der den Kauf tätigt
  • transactionMerchant: Informationen zum Händler, der die Bestellung durchgeführt hat.
  • contents: Der tatsächliche Inhalt des Auftrags, der als lineItems aufgeführt ist.
  • priceAttributes: Preisdetails zur Bestellung, einschließlich der Gesamtkosten der Bestellung mit Rabatten und Steuern.

Informationen zum Erstellen des Einkaufswagens findest du in der Dokumentation zu Order-Antworten. Je nach Reihenfolge müssen Sie unter Umständen andere Felder hinzufügen.

Der Beispielcode unten zeigt eine vollständige Bestellung mit optionalen Feldern:

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',
  },
};

Auftrags- und Präsentationsoptionen erstellen

Bevor der Nutzer seine Bestellung bestätigt, wird ihm eine vorgeschlagene Bestellkarte angezeigt. Sie können die Darstellung dieser Karte für den Nutzer anpassen, indem Sie verschiedene Reihenfolge- und Präsentationsoptionen festlegen.

Nachfolgend finden Sie Bestell- und Präsentationsoptionen für eine Bestellung, für die eine Lieferadresse erforderlich ist, einschließlich der E-Mail-Adresse des Nutzers auf der Karte mit der Bestellbestätigung:

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

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

Zahlungsparameter erstellen

Das paymentParameters-Objekt enthält Tokenisierungsparameter, die sich je nach Google Pay-Auftragsverarbeiter ändern, den Sie verwenden möchten (z. B. Stripe, Braintree, ACI usw.).

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',
          },
        }),
      },
    };

Der Inhalt des Objekts tokenizationSpecification ist je nach Zahlungsgateway unterschiedlich. Die folgende Tabelle zeigt die von jedem Gateway verwendeten Parameter:

BEISPIEL
"parameters": {
  "gateway": "example",
  "gatewayMerchantId": "exampleGatewayMerchantId"
}
ACI
"parameters": {
  "gateway": "aciworldwide",
  "gatewayMerchantId": "YOUR_ENTITY_ID"
}
ADYEN
"parameters": {
  "gateway": "adyen",
  "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"
}
ALFA-BANK
"parameters": {
  "gateway": "alfabank",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BLUE_MEDIA
"parameters": {
  "gateway": "bluemedia",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BLAUESNAP
"parameters": {
  "gateway": "bluesnap",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BRAINTRE
"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
"parameters": {
  "gateway": "chase",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER"
}
ZAHLUNG
"parameters": {
  "gateway": "checkoutltd",
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"
}
CLOUDPAYMENTS
"parameters": {
  "gateway": "cloudpayments",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
CYBERSOURCE
"parameters": {
  "gateway": "cybersource",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
DATENTRANS
"parameters": {
  "gateway": "datatrans",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
EBANX
"parameters": {
  "gateway": "ebanx",
  "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"
}
FIRST_DATA
"parameters": {
  "gateway": "firstdata",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
GLOBAL_PAYMENTS
"parameters": {
  "gateway": "globalpayments",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
GOPAY
"parameters": {
  "gateway": "gopay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
HITRUST
"parameters": {
  "gateway": "hitrustpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
IMLÖSUNGEN
"parameters": {
  "gateway": "imsolutions",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
LYRA
"parameters": {
  "gateway": "lyra",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
MPGS
"parameters": {
  "gateway": "mpgs",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
GELD_MAIL_RU
"parameters": {
  "gateway": "moneymailru",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NEWEBPAY
"parameters": {
  "gateway": "newebpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NEXI
"parameters": {
  "gateway": "nexi",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
NMI
"parameters": {
  "gateway": "creditcall",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYSAFE
"parameters": {
  "gateway": "paysafe",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYTURE
"parameters": {
  "gateway": "payture",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYU
"parameters": {
  "gateway": "payu",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PRZELEWY24
"parameters": {
  "gateway": "przelewy24",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
RBKMONEY
"parameters": {
  "gateway": "rbkmoney",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
SBERBANK
"parameters": {
  "gateway": "sberbank",
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
}
QUADRAT
"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
STREICHEN
"parameters": {
  "gateway": "stripe",
  "stripe:version": "2018-10-31",
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
}
TAPPAY
"parameters": {
  "gateway": "tappay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
TINKOFF
"parameters": {
  "gateway": "tinkoff",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
UNITELLER
"parameters": {
  "gateway": "uniteller",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
VANTIV
"parameters": {
  "gateway": "vantiv",
  "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID",
  "vantiv:merchantOrderId": "YOUR_ORDER_ID",
  "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID",
  "vantiv:merchantReportGroup": "*web"
}
WORLDPAY
"parameters": {
  "gateway": "worldpay",
  "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"
}
YANDEX
"parameters": {
  "gateway": "yandexcheckout",
  "gatewayMerchantId": "YOUR_SHOP_ID"
}

Bestelldaten im Sitzungsparameter speichern

Speichern Sie die Bestelldaten aus der Auftragsausführung in einem Sitzungsparameter. Das Order-Objekt wird szenenübergreifend für dieselbe Sitzung verwendet.

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

Auftrag vorschlagen

Nachdem Sie einen Auftrag erstellt haben, müssen Sie ihn dem Nutzer zur Bestätigung oder zur Ablehnung vorlegen. Wechseln Sie dazu zu einer Szene, die eine Transaktionsentscheidung ausführt.

Szene für Transaktionsentscheidung erstellen

  1. Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen TransactionDecision hinzu.
  2. Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
  3. Wählen Sie unter Typ auswählen actions.type.TransactionDecisionValue als Slottyp aus.
  4. Geben Sie der Anzeigenfläche den Namen TransactionDecision im Feld für den Slotnamen.
  5. Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
  6. Wählen Sie unter Slot konfigurieren im Drop-down-Menü die Option Sitzungsparameter verwenden aus.
  7. Geben Sie unter Slot konfigurieren den Namen des Sitzungsparameters ein,der zum Speichern der Bestellung im Textfeld verwendet wird (z.B. $session.params.order).
  8. Klicken Sie auf Speichern.

Beim Versuch, einen TransactionDecisionValue-Slot zu füllen, initiiert Assistant eine integrierte Funktion, bei der die übergebene Order direkt auf einer „Warenkorbvorschaukarte“ gerendert wird. Der Nutzer kann „Bestellung aufgeben“ sagen, die Transaktion ablehnen, eine Zahlungsoption wie Kreditkarte oder Adresse ändern oder eine Änderung des Bestellinhalts anfordern.

An dieser Stelle kann der Nutzer auch Änderungen an der Bestellung anfordern. In diesem Fall sollten Sie dafür sorgen, dass die Auftragsausführung nach Abschluss der Warenkorbmontage Anfragen zu Bestelländerungen bearbeiten kann.

Transaktionsentscheidungsergebnis verarbeiten

Wenn ein TransactionDecisionValue-Slot gefüllt wird, wird die Antwort des Nutzers auf die Transaktionsentscheidung in einem Sitzungsparameter gespeichert. Dieser Wert enthält Folgendes:

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

So verarbeiten Sie das Ergebnis einer Transaktionsentscheidung:

  1. Wählen Sie auf dem Tab Szenen die neu erstellte Szene TransactionDecision aus.
  2. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
  3. Geben Sie die folgende Bedingungssyntax in das Textfeld ein, um zu prüfen, ob die Erfolgsbedingung erfüllt ist:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  4. Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor if scene.slots.status == "FINAL" zu platzieren.

  5. Aktivieren Sie Aufforderungen senden und geben Sie eine einfache Aufforderung an, die den Nutzer darüber informiert, dass seine Bestellung abgeschlossen ist:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction completed! Your order
                $session.params.TransactionDecision.order.merchantOrderId is all
                set!
    
  6. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus.

  7. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.

  8. Geben Sie in das Textfeld die folgende Bedingungssyntax ein, um nach den Fehlerbedingungen zu suchen:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
    
  9. Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor if scene.slots.status == "FINAL" zu platzieren.

  10. Aktivieren Sie Aufforderungen senden und zeigen Sie dem Nutzer mit einer einfachen Aufforderung an, dass die Bestellung abgelehnt wurde:

    candidates:
      - first_simple:
          variants:
            - speech: Look like you don't want to order anything. Goodbye.
    
  11. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus.

  12. Wählen Sie die Bedingung else if scene.slots.status == "FINAL" aus.

  13. Aktivieren Sie SendPrompts (Aufforderungen senden) und geben Sie dem Nutzer eine einfache Aufforderung an, damit er weiß, dass er keine Transaktion vornehmen kann:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction failed with status
                $session.params.TransactionDecision.transactionDecision
    
  14. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.

Bestellung abschließen und Beleg senden

Wenn der Slot TransactionDecisionValue das Ergebnis ORDER_ACCEPTED zurückgibt, müssen Sie sofort die Verarbeitung ausführen, die zum "Bestätigen" der Bestellung erforderlich ist. Sie können sie beispielsweise in Ihrer eigenen Datenbank speichern und dem Nutzer in Rechnung stellen.

Sie können die Unterhaltung mit dieser Antwort beenden, müssen aber eine einfache Antwort hinzufügen, um die Unterhaltung am Laufen zu halten. Wenn du diese anfängliche orderUpdate angibst, sieht der Nutzer eine minimierte Belegkarte zusammen mit dem Rest deiner Antwort. Diese Karte spiegelt den Beleg wider, den der Nutzer in seinem Bestellverlauf findet.

Während der Bestellbestätigung kann das Bestellobjekt eine userVisibleOrderId enthalten. Das ist die ID, die der Nutzer für die Bestellung sieht. Sie können die merchantOrderId für dieses Feld wiederverwenden.

Ein Teil des OrderUpdate-Objekts muss ein Follow-up-Action-Objekt enthalten, das sich in Form von URL-Schaltflächen am Ende der Bestelldetails befindet, die der Nutzer in seinem Assistant-Bestellverlauf finden kann.

  • Für jede Bestellung müssen Sie mindestens eine VIEW_DETAILS-Folgeaktion angeben. Dieser sollte einen Deeplink zur Darstellung der Bestellung in Ihrer mobilen App oder Website enthalten.
  • Zusätzlich zur Empfangskarte in der Unterhaltung deiner Aktion musst du per E-Mail einen formellen Beleg senden, der alle rechtlichen Anforderungen für die Durchführung einer Transaktion erfüllt.

So senden Sie eine erste Bestellaktualisierung:

  1. Wähle auf dem Tab Szenen deine TransactionDecision-Szene aus.
  2. Wählen Sie unter Bedingung die Bedingung aus, die das Erfolgsergebnis ORDER_ACCEPTED prüft:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  3. Aktivieren Sie für diese Bedingung Webhook aufrufen und geben Sie einen Intent-Handler-Namen wie update_order an.

  4. Fügen Sie dem Webhook-Code einen Intent-Handler hinzu, um eine anfängliche Bestellaktualisierung zu senden:

    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
      }));
    });
    

Bestellaktualisierungen senden

Sie müssen den Nutzer während der gesamten Lebensdauer über den Status der Bestellung informieren. Senden Sie dem Nutzer Bestellaktualisierungen, indem Sie HTTP-PATCH-Anfragen mit Bestellstatus und -details an die Orders API senden.

Asynchrone Anfragen an die Orders API einrichten

Anfragen zur Bestellaktualisierung an die Orders API werden durch ein Zugriffstoken autorisiert. Wenn du eine Bestellaktualisierung mit PATCH für die Orders API durchführen möchtest, lade einen JSON-Dienstkontoschlüssel herunter, der mit deinem Actions Console-Projekt verknüpft ist, und tauschen Sie den Dienstkontoschlüssel gegen ein Inhabertoken aus, das an den Authorization-Header der HTTP-Anfrage übergeben werden kann.

Führen Sie die folgenden Schritte aus, um Ihren Dienstkontoschlüssel abzurufen:

  1. Gehen Sie in der Google Cloud Console zu Menü ⋮ > APIs und Dienste > Anmeldedaten > Anmeldedaten erstellen > Dienstkontoschlüssel.
  2. Wählen Sie unter Dienstkonto die Option Neues Dienstkonto aus.
  3. Legen Sie das Dienstkonto auf service-account fest.
  4. Stellen Sie die Rolle auf Projekt > Inhaber ein.
  5. Legen Sie den Schlüsseltyp auf JSON fest.
  6. Wählen Sie Erstellen aus.
  7. Ein privater JSON-Dienstkontoschlüssel wird auf Ihren lokalen Computer heruntergeladen.

Im Code für die Aktualisierung Ihrer Bestellung können Sie Ihren Dienstschlüssel mithilfe der Google APIs-Clientbibliothek und dem Bereich "https://www.googleapis.com/auth/actions.order.developer" gegen ein Inhabertoken austauschen. Installationsschritte und Beispiele finden Sie auf der GitHub-Seite der API-Clientbibliothek.

Als Beispiel für einen Schlüsselaustausch können Sie auch auf order-update.js in unserem Node.js-Beispiel verweisen.

Bestellaktualisierungen senden

Nachdem Sie Ihren Dienstkontoschlüssel gegen ein OAuth-Inhabertoken ausgetauscht haben, können Sie Bestellaktualisierungen als autorisierte PATCH-Anfragen an die Orders API senden.

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

Geben Sie in Ihrer Anfrage die folgenden Header an:

  • "Authorization: Bearer token" durch das OAuth-Inhabertoken, gegen das Sie Ihren Dienstkontoschlüssel ausgetauscht haben.
  • "Content-Type: application/json".

Die PATCH-Anfrage sollte einen JSON-Text im folgenden Format haben:

{ "orderUpdate": OrderUpdate }

Das Objekt OrderUpdate besteht aus den folgenden Feldern der obersten Ebene:

  • updateMask: die Felder des Auftrags, den Sie aktualisieren Wenn Sie den Bestellstatus aktualisieren möchten, legen Sie den Wert auf purchase.status, purchase.userVisibleStatusLabel fest.
  • order: Der Inhalt des Updates. Wenn du den Inhalt der Bestellung aktualisierst, lege den Wert auf das aktualisierte Order-Objekt fest. Wenn Sie den Status der Bestellung aktualisieren (z. B. von "CONFIRMED" zu "SHIPPED"), enthält das Objekt die folgenden Felder:

    • merchantOrderId: Dies ist die ID, die Sie im Order-Objekt festgelegt haben.
    • lastUpdateTime: Der Zeitstempel dieser Aktualisierung.
    • purchase: ein Objekt, das Folgendes enthält:
      • status: Der Status der Bestellung als PurchaseStatus, z. B. „SHIPPED“ oder „DELIVERED“.
      • userVisibleStatusLabel: ein für den Nutzer sichtbares Label mit Details zum Bestellstatus, z. B. „Ihre Bestellung wurde versandt und ist unterwegs“.
  • userNotification (optional) – Ein userNotification-Objekt, das auf dem Gerät des Nutzers angezeigt werden kann, wenn dieses Update gesendet wird. Das Hinzufügen dieses Objekts garantiert jedoch nicht, dass eine Benachrichtigung auf dem Gerät des Nutzers erscheint.

Der folgende Beispielcode zeigt ein OrderUpdate-Beispiel, das den Status der Bestellung in DELIVERED aktualisiert:

// 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}`);
}
Kaufstatus festlegen

Der status einer Bestellaktualisierung muss eine Beschreibung des aktuellen Status der Bestellung enthalten. Verwenden Sie im Feld order.purchase.status des Updates einen der folgenden Werte:

  • CREATED: Die Reihenfolge wird vom Nutzer akzeptiert und aus Sicht deiner Aktion „erstellt“, erfordert jedoch eine manuelle Verarbeitung auf deinem Back-End.
  • CONFIRMED: Die Bestellung ist aktiv und wird zwecks Auftragsausführung verarbeitet.
  • IN_PREPARATION: Die Bestellung wird für den Versand/die Lieferung vorbereitet, z. B. wenn Essen gekocht oder ein Artikel verpackt wird.
  • READY_FOR_PICKUP: Die Bestellung kann vom Empfänger abgeholt werden.
  • DELIVERED – Bestellung wurde an den Empfänger zugestellt
  • OUT_OF_STOCK: Mindestens ein Artikel in der Bestellung ist nicht auf Lager.
  • CHANGE_REQUESTED: Der Nutzer hat eine Änderung an der Bestellung angefordert und die Änderung wird verarbeitet.
  • RETURNED: Die Bestellung wurde vom Nutzer nach der Lieferung zurückgegeben.
  • REJECTED: Wenn Sie die Bestellung nicht verarbeiten, in Rechnung stellen oder anderweitig „aktivieren“ konnten.
  • CANCELLED: Die Bestellung wurde vom Nutzer storniert.

Sie sollten Bestellaktualisierungen für jeden für Ihre Transaktion relevanten Status senden. Wenn Ihre Transaktion beispielsweise eine manuelle Verarbeitung erfordert, um die Bestellung nach ihrer Aufgabe zu protokollieren, senden Sie eine CREATED-Bestellaktualisierung, bis die zusätzliche Verarbeitung abgeschlossen ist. Nicht für jede Bestellung ist jeder Statuswert erforderlich.

Projekt testen

Beim Testen deines Projekts kannst du den Sandbox-Modus in der Actions Console aktivieren, um deine Aktion zu testen, ohne eine Zahlungsmethode zu belasten. So aktivieren Sie den Sandbox-Modus:

  1. Klicken Sie in der Actions Console im Navigationsbereich auf Test.
  2. Klicke auf Einstellungen.
  3. Aktivieren Sie die Option Entwicklungs-Sandbox.

Für physische Transaktionen können Sie das Feld isInSandbox in Ihrem Beispiel auch auf true setzen. Diese Aktion entspricht dem Aktivieren der Einstellung für den Sandbox-Modus in der Actions Console. Ein Code-Snippet, in dem isInSandbox verwendet wird, findest du im Abschnitt Bestellaktualisierungen senden.

Fehlerbehebung

Wenn während des Tests Probleme auftreten, lesen Sie unsere Schritte zur Fehlerbehebung für Transaktionen.