Tworzenie transakcji fizycznych za pomocą Google Pay

Z tego przewodnika dowiesz się, jak opracować projekt w Actions, który obejmuje transakcje sprzedaży towarów fizycznych i używa płatności za pomocą Google Pay.

Przepływ transakcji

Gdy Twój projekt Actions obsługuje transakcje fizyczne z wykorzystaniem płatności zarządzanych przez sprzedawcę, korzysta z tego procesu:

  1. Zbieranie informacji (opcjonalne) – w zależności od charakteru transakcji możesz na początku rozmowy uzyskać od użytkownika te informacje:
    1. Sprawdzanie wymagań dotyczących transakcji – na początku rozmowy sprawdź, czy użytkownik spełnia wymagania konieczne do zrealizowania transakcji, takie jak prawidłowo skonfigurowane i dostępne dane karty, zanim utworzysz koszyk.
    2. Poproś o adres dostawy – jeśli transakcja wymaga podania adresu dostawy, uzyskaj go od użytkownika.
  2. Stworzenie zamówienia – poprowadź użytkownika przez proces składania koszyka, w którym wybiera produkty, które chce kupić.
  3. Proponowanie zamówienia – gdy koszyk jest gotowy, zaproponuj zamówienie użytkownikowi, aby mógł potwierdzić, że jest poprawne. Jeśli zamówienie zostanie potwierdzone, otrzymasz odpowiedź ze szczegółami zamówienia i tokenem płatności.
  4. Sfinalizuj zamówienie i wyślij potwierdzenie – po potwierdzeniu zamówienia zaktualizuj śledzenie asortymentu lub inne usługi realizacji zamówień, a potem wyślij użytkownikowi potwierdzenie.
  5. Wysyłanie aktualizacji zamówień – w trakcie okresu realizacji zamówienia przekazuj aktualizacje zamówienia użytkownika, wysyłając żądania PATCH do interfejsu Orders API.

Ograniczenia i wytyczne dotyczące sprawdzania

Pamiętaj, że w przypadku akcji z transakcjami obowiązują dodatkowe zasady. Sprawdzenie działań z transakcjami może nam zająć do 6 tygodni, więc uwzględnij ten czas przy planowaniu harmonogramu publikacji. Aby ułatwić proces sprawdzania, przed przesłaniem akcji do sprawdzenia upewnij się, że przestrzegasz zasad i wytycznych dotyczących transakcji.

Akcje, które sprzedają towary fizyczne, możesz wdrażać tylko w tych krajach:

Australia
Brazylia
Kanada
Indonezja
Japonia
Meksyk
Rosja
Singapur
Tajlandia
Turcja
Wielka Brytania
Stany Zjednoczone

Utwórz projekt

Obszerne przykłady rozmów transakcyjnych znajdziesz w przykładzie transakcji w Node.js.

Konfiguracja

Podczas tworzenia akcji musisz określić, że chcesz przeprowadzać transakcje w Konsoli Actions.

Aby skonfigurować projekt i realizację:

  1. Utwórz nowy projekt lub zaimportuj istniejący.
  2. Kliknij Wdróż > Informacje z katalogu.
  3. W sekcji Dodatkowe informacje > Transakcje zaznacz pole „Czy Twoje działania używają interfejsu Transaction API do realizacji transakcji towarów fizycznych?”.

1. Zbieranie informacji (opcjonalnie)

1a. Zweryfikuj wymagania dotyczące transakcji (opcjonalnie)

Gdy tylko użytkownik wyrazi chęć zakupu, należy sprawdzić, czy może zrealizować transakcję. Po wywołaniu akcja może np. zapytać: „Czy chcesz zamówić buty, czy sprawdzić saldo konta?”. Jeśli użytkownik powie „zamów buty”, dopilnuj, by mógł kontynuować i umożliwił mu poprawienie ustawień, które uniemożliwiają kontynuowanie transakcji. Aby to zrobić, należy przejść na scenę, która sprawdza wymagania dotyczące transakcji.

Tworzenie sceny kontroli wymagań transakcji
  1. Na karcie Sceny dodaj nową scenę o nazwie TransactionRequirementsCheck.
  2. W sekcji Wypełnianie przedziałów kliknij +, aby dodać nowe boksy.
  3. W sekcji Wybierz typ wybierz actions.type.TransactionRequirementsCheckResult jako typ boksu.
  4. W polu nazwy boksu nadaj boksowi nazwę TransactionRequirementsCheck.
  5. Zaznacz pole wyboru Dostosuj zapis wartości przedziału (domyślnie włączone).
  6. Kliknij Zapisz.

Sprawdzenie pod kątem wymagań dotyczących transakcji zaowocuje jednym z tych wyników:

  • Jeśli zostaną spełnione wymagania, parametr sesji jest ustawiany jako warunek powodzenia i możesz kontynuować tworzenie zamówienia użytkownika.
  • Jeśli nie można spełnić co najmniej jednego z wymagań, parametr sesji jest ustawiany z warunkem niepowodzenia. W takim przypadku należy odwrócić rozmowę od procesu transakcyjnego lub zakończyć rozmowę.
    • Jeśli użytkownik będzie w stanie naprawić błędy, które spowodowały błąd, pojawi się prośba o rozwiązanie tych problemów na urządzeniu. Jeśli rozmowa odbywa się tylko na platformie głosowej, na telefonie użytkownika zostanie zainicjowane przekazanie wiadomości.

Obsługa wyniku kontroli wymagań dotyczących transakcji

  1. Na karcie Sceny wybierz nowo utworzoną scenę TransactionRequirementsCheck.
  2. W sekcji Warunek kliknij +, by dodać nowy warunek.
  3. W polu tekstowym wpisz tę składnię warunku, aby sprawdzić, czy występuje warunek powodzenia:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
    
  4. Najedź kursorem na dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

  5. Włącz Wyślij potwierdzenia i daj użytkownikowi znać, że jest gotowy do dokonania transakcji:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase physical goods.
    
  6. W sekcji Przejście wybierz inną scenę, aby użytkownik mógł kontynuować rozmowę i dokonać transakcji.

  7. Wybierz warunek else if scene.slots.status == "FINAL".

  8. Włącz Wysyłanie potwierdzeń i wyświetlaj proste powiadomienie informujące użytkownika, że nie może dokonać transakcji:

    candidates:
      - first_simple:
          variants:
            - speech: Transaction requirements check failed.
    
  9. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę, jeśli użytkownik nie może dokonać transakcji.

Wysyłanie prośby o adres dostawy

Jeśli transakcja wymaga podania adresu dostawy użytkownika, musisz go o to poprosić. Może to być przydatne do określania łącznej ceny, miejsca dostawy i odbioru oraz do sprawdzania, czy użytkownik znajduje się w regionie, w którym świadczysz usługi. Aby to zrobić, przejdź do sceny, w której pojawi się prośba do użytkownika o podanie adresu dostawy.

Tworzenie sceny adresu dostawy

  1. Na karcie Sceny dodaj nową scenę o nazwie DeliveryAddress.
  2. W sekcji Wypełnianie przedziałów kliknij +, aby dodać nowe boksy.
  3. W sekcji Wybierz typ wybierz actions.type.DeliveryAddressValue jako typ boksu.
  4. W polu nazwy boksu nadaj boksowi nazwę TransactionDeliveryAddress.
  5. Zaznacz pole wyboru Dostosuj zapis wartości przedziału (domyślnie włączone).
  6. Kliknij Zapisz.

Podczas konfigurowania przedziału możesz podać element reason, który umożliwi poprzedzanie żądania Asystenta o uzyskanie adresu ciągiem tekstowym.Domyślnym ciągiem znaków przyczyny jest „dowiedzieć się, gdzie wysłać zamówienie”. Dlatego Asystent może zapytać użytkownika: „Aby dowiedzieć się, gdzie wysłać zamówienie, muszę poznać Twój adres dostawy”.

  • Na platformach z ekranem użytkownik wybiera adres, którego chce użyć do zrealizowania transakcji. Jeśli klient nie podał wcześniej adresu, może wpisać nowy.
  • W usługach z obsługą tylko głosu Asystent poprosi użytkownika o zgodę na udostępnienie domyślnego adresu tej transakcji. Jeśli rozmówca nie podał wcześniej adresu, rozmowa zostanie przekazana do telefonu.

Aby obsłużyć wynik adresu dostawy, wykonaj te czynności:

  1. Na karcie Sceny wybierz nowo utworzoną scenę DeliveryAddress.
  2. W sekcji Warunek kliknij +, by dodać nowy warunek.
  3. W polu tekstowym wpisz tę składnię warunku, aby sprawdzić, czy występuje warunek powodzenia:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
    
  4. Najedź kursorem na dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

  5. Włącz Wysyłaj potwierdzenia i wyświetlaj użytkownikowi prostą wiadomość, która informuje użytkownika, że jego adres został odebrany:

    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 sekcji Przejście wybierz inną scenę, aby użytkownik mógł kontynuować rozmowę.

  7. Wybierz warunek else if scene.slots.status == "FINAL".

  8. Włącz Wysyłanie potwierdzeń i wyświetlaj proste powiadomienie informujące użytkownika, że nie może dokonać transakcji:

    candidates:
      - first_simple:
          variants:
            - speech: I failed to get your delivery address.
    
  9. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę, jeśli użytkownik nie może dokonać transakcji.

Tworzenie zamówienia

Po otrzymaniu potrzebnych informacji o użytkowniku utworzysz proces „składania koszyka”, który pomoże mu złożyć zamówienie. W przypadku każdego akcji proces składania koszyka jest trochę inny, zależnie od produktu lub usługi.

Najbardziej podstawowa metoda montażu koszyka polega na tym, że użytkownik wybiera produkty z listy, aby dodać je do zamówienia. Możesz jednak tak zaprojektować rozmowę, aby uprościć korzystanie z niej. Możesz utworzyć funkcję składania koszyka, która pozwoli użytkownikowi ponownie zamówić ostatni zakup, używając prostego pytania typu „tak” lub „nie”. Możesz też pokazać użytkownikowi karuzelę lub listę najczęściej polecanych elementów.

Zalecamy stosowanie odpowiedzi rozszerzonych, aby wizualnie przedstawić opcje użytkownika, a także tak zaprojektować rozmowę, aby mógł utworzyć koszyk tylko za pomocą głosu. Sprawdzone metody i przykłady wysokiej jakości sposobów składania koszyka znajdziesz w wytycznych dotyczących projektowania.

Tworzenie zamówienia

W trakcie rozmowy musisz zgromadzić produkty, które użytkownik chce kupić, a potem utworzyć obiekt Order.

Order musi zawierać co najmniej:

  • buyerInfo – informacje o użytkowniku dokonującym zakupu.
  • transactionMerchant – informacje o sprzedawcy, który złożył zamówienie.
  • contents – rzeczywista zawartość zamówienia podana jako lineItems.
  • priceAttributes – szczegółowe informacje o cenie zamówienia, w tym jego łączny koszt z rabatami i podatkami.

Aby utworzyć koszyk, zapoznaj się z dokumentacją odpowiedzi Order. Pamiętaj, że w zależności od zamówienia może być konieczne dodanie różnych pól.

Przykładowy kod poniżej pokazuje pełne zamówienie, z uwzględnieniem pól opcjonalnych:

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

Opcje tworzenia kolejności i prezentacji

Zanim użytkownik potwierdzi zamówienie, zobaczy proponowaną kartę zamówienia. Możesz dostosować sposób wyświetlania tej karty użytkownikowi, ustawiając różne opcje kolejności i prezentacji.

Poniżej znajdują się opcje składania zamówień i prezentowania ich w ramach składania zamówień, które wymagają podania adresu dostawy, w tym adres e-mail użytkownika widoczny na karcie potwierdzenia zamówienia:

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

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

Tworzenie parametrów płatności

Obiekt paymentParameters będzie zawierał parametry tokenizacji, które zmieniają się w zależności od firmy obsługującej Google Pay, z której zamierzasz korzystać (np. Stripe, Braintree, ACI itp.).

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

Zawartość obiektu tokenizationSpecification jest inna w przypadku każdej bramy płatności. W tabeli poniżej znajdziesz parametry używane przez każdą bramę:

PRZYKŁAD
"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"
}
BLUESNAP
"parameters": {
  "gateway": "bluesnap",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
BRAINTREE
"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"
}
PŁATNOŚĆ
"parameters": {
  "gateway": "checkoutltd",
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"
}
CLOUDPAYMENTS
"parameters": {
  "gateway": "cloudpayments",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
CYBERSOURCE
"parameters": {
  "gateway": "cybersource",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
DATATRANS
"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"
}
IMSOLUTCJE
"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"
}
ji_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"
}
PŁATNOŚĆ
"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"
}
KWADRAT
"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
StripE
"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"
}

Zapisz dane zamówienia w parametrze sesji

Na stronie realizacji zamówienia zapisz dane zamówienia w parametrze sesji. Obiekt zamówienia będzie używany w różnych scenach w tej samej sesji.

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

Zaproponuj zamówienie

Po utworzeniu zamówienia musisz przedstawić je użytkownikowi, aby mógł je potwierdzić lub odrzucić. Aby to zrobić, należy przejść do sceny, w której dokonywana jest decyzja o transakcji.

Tworzenie sceny podejmowania decyzji o transakcji

  1. Na karcie Sceny dodaj nową scenę o nazwie TransactionDecision.
  2. W sekcji Wypełnianie przedziałów kliknij +, aby dodać nowe boksy.
  3. W sekcji Wybierz typ wybierz actions.type.TransactionDecisionValue jako typ boksu.
  4. W polu nazwy boksu nadaj boksowi nazwę TransactionDecision.
  5. Zaznacz pole wyboru Dostosuj zapis wartości przedziału (domyślnie włączone).
  6. W sekcji Skonfiguruj przedział wybierz z menu Użyj parametru sesji.
  7. W sekcji Skonfiguruj przedział wpisz w polu tekstowym nazwę parametru sesji używanego do przechowywania zamówienia (np. $session.params.order).
  8. Kliknij Zapisz.

Próbując wypełnić boks TransactionDecisionValue, Asystent inicjuje wbudowane środowisko, w którym przekazywana wartość Order jest renderowana bezpośrednio na „karcie podglądu koszyka”. Użytkownik może powiedzieć „złóż zamówienie”, odrzucić transakcję, zmienić opcję płatności (np. kartę kredytową lub adres) lub poprosić o zmianę zawartości zamówienia.

W tym momencie użytkownik może też poprosić o zmianę zamówienia. W takim przypadku upewnij się, że po zakończeniu procesu składania zamówień realizacja zamówień może być obsługiwana przez prośby o zmianę zamówienia.

Obsługa wyniku decyzji o transakcji

Po wypełnieniu boksu TransactionDecisionValue odpowiedź użytkownika na decyzję o transakcji zostanie zapisana w parametrze sesji. Ta wartość obejmuje te elementy:

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

Aby obsługiwać wynik decyzji o transakcji:

  1. Na karcie Sceny wybierz nowo utworzoną scenę TransactionDecision.
  2. W sekcji Warunek kliknij +, by dodać nowy warunek.
  3. W polu tekstowym wpisz tę składnię warunku, aby sprawdzić, czy został on spełniony:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  4. Najedź kursorem na dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

  5. Włącz Wysyłanie potwierdzeń i wyświetlaj proste powiadomienie informujące użytkownika, że zamówienie zostało zrealizowane:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction completed! Your order
                $session.params.TransactionDecision.order.merchantOrderId is all
                set!
    
  6. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę.

  7. W sekcji Warunek kliknij +, by dodać nowy warunek.

  8. W polu tekstowym wpisz tę składnię warunku, aby sprawdzić, czy nie wystąpił błąd:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
    
  9. Najedź kursorem na dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

  10. Włącz Wyślij potwierdzenia i podaj użytkownikowi prostą wiadomość, która poinformuje użytkownika o odrzuceniu zamówienia:

    candidates:
      - first_simple:
          variants:
            - speech: Look like you don't want to order anything. Goodbye.
    
  11. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę.

  12. Wybierz warunek else if scene.slots.status == "FINAL".

  13. Włącz Wysyłanie potwierdzeń i wyświetlaj proste powiadomienie informujące użytkownika, że nie może dokonać transakcji:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction failed with status
                $session.params.TransactionDecision.transactionDecision
    
  14. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę, jeśli użytkownik nie może dokonać transakcji.

Sfinalizuj zamówienie i wyślij potwierdzenie

Gdy przedział TransactionDecisionValue zwraca wynik funkcji ORDER_ACCEPTED, musisz natychmiast wykonać przetwarzanie wymagane do „potwierdzenia” zamówienia (np. zapisanie go w Twojej bazie danych i obciążenie użytkownika).

Możesz zakończyć rozmowę tą odpowiedzią, ale musisz dołączyć prostą odpowiedź, aby kontynuować rozmowę. Gdy podasz tę pierwszą część (orderUpdate), użytkownik zobaczy „zwiniętą kartę potwierdzenia” wraz z resztą Twojej odpowiedzi. Ta karta będzie odzwierciedlał rachunek, który użytkownik znajdzie w swojej historii zamówień.

W trakcie potwierdzenia zamówienia obiekt może zawierać userVisibleOrderId, czyli identyfikator, który widzi użytkownik. Możesz ponownie użyć w tym polu pola merchantOrderId.

Część obiektu OrderUpdate musi zawierać obiekt działania kontrolnego, który wyświetla się jako przyciski adresu URL u dołu szczegółów zamówienia, które użytkownik może znaleźć w historii zamówień Asystenta.

  • Do każdego zamówienia musisz dołączyć co najmniej 1 działanie dodatkowe (VIEW_DETAILS). Powinien on zawierać precyzyjny link do treści zamówienia w aplikacji mobilnej lub witrynie.
  • Oprócz karty potwierdzenia w rozmowie w ramach akcji musisz też wysłać e-mailem oficjalne potwierdzenie spełniające wszystkie wymagania prawne do przeprowadzenia transakcji.

Aby wysłać wstępną aktualizację zamówienia:

  1. Na karcie Sceny wybierz scenę TransactionDecision.
  2. W sekcji Warunek wybierz warunek, który ma sprawdzić powodzenie:ORDER_ACCEPTED

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  3. W przypadku tego warunku włącz Wywołaj webhooka i podaj nazwę modułu obsługi intencji, np. update_order.

  4. W kodzie webhooka dodaj moduł obsługi intencji, który służy do wysyłania początkowej aktualizacji zamówienia:

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

Wysyłanie aktualizacji zamówienia

Musisz informować użytkownika o stanie zamówienia przez cały okres jego ważności. Wysyłaj aktualizacje zamówień użytkownika, wysyłając do interfejsu Orders API żądania HTTP PATCH ze stanem i szczegółami zamówienia.

Konfigurowanie żądań asynchronicznych kierowanych do interfejsu Orders API

Żądania aktualizacji zamówień wysyłane do interfejsu Orders API są autoryzowane przez token dostępu. Aby ŁATWIĆ aktualizację zamówienia do interfejsu Orders API, pobierz klucz konta usługi JSON powiązany z projektem w Actions Console, a następnie wymień klucz konta usługi na token okaziciela, który można przekazać do nagłówka Authorization żądania HTTP.

Aby pobrać klucz konta usługi, wykonaj te czynności:

  1. W konsoli Google Cloud wybierz Menu />< > Interfejsy API i usługi > Dane logowania > Utwórz dane logowania > Klucz konta usługi.
  2. W sekcji Service Account (Konto usługi) wybierz New Service Account (Nowe konto usługi).
  3. Ustaw konto usługi na service-account.
  4. Ustaw Rolę na Projekt > Właściciel.
  5. Ustaw typ klucza na JSON.
  6. Wybierz Utwórz.
  7. Na Twój komputer zostanie pobrany prywatny klucz konta usługi JSON.

W kodzie aktualizacji zamówień możesz wymienić klucz usługi na token okaziciela, korzystając z biblioteki klienta interfejsów API Google i zakresu "https://www.googleapis.com/auth/actions.order.developer". Instrukcje instalacji i przykłady znajdziesz na stronie w GitHubie w bibliotece klienta interfejsu API.

Przykład wymiany kluczy możesz znaleźć w order-update.js w naszym przykładzie Node.js.

Wysyłanie aktualizacji zamówienia

Po wymianie klucza konta usługi na token okaziciela OAuth możesz wysyłać aktualizacje zamówień jako autoryzowane żądania PATCH do interfejsu Orders API.

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

Podaj te nagłówki w żądaniu:

  • "Authorization: Bearer token" z tokenem okaziciela OAuth, na który wymieniono klucz konta usługi.
  • "Content-Type: application/json".

Żądanie PATCH powinno mieć treść JSON w tym formacie:

{ "orderUpdate": OrderUpdate }

Obiekt OrderUpdate składa się z tych pól najwyższego poziomu:

  • updateMask – pola zamówienia, które aktualizujesz. Aby zaktualizować stan zamówienia, ustaw wartość na purchase.status, purchase.userVisibleStatusLabel.
  • order – zawartość aktualizacji. Jeśli aktualizujesz zawartość zamówienia, ustaw wartość na zaktualizowany obiekt Order. Jeśli aktualizujesz stan zamówienia (na przykład z "CONFIRMED" na "SHIPPED"), obiekt zawiera te pola:

    • merchantOrderId – identyfikator ustawiony w obiekcie Order.
    • lastUpdateTime – sygnatura czasowa aktualizacji.
    • purchase – obiekt zawierający:
      • status – stan zamówienia to PurchaseStatus, np. „SHIPPED” lub „DELIVERED”.
      • userVisibleStatusLabel – widoczna dla użytkowników etykieta ze szczegółowymi informacjami o stanie zamówienia, np. „Twoje zamówienie zostało wysłane i jest w drodze”.
  • userNotification, który może się wyświetlać na urządzeniu użytkownika po wysłaniu tej aktualizacji. Pamiętaj, że uwzględnienie tego obiektu nie gwarantuje, że powiadomienie pojawi się na urządzeniu użytkownika.

Poniżej znajduje się przykładowy kod OrderUpdate, który aktualizuje stan zamówienia na 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}`);
}
Ustawianie stanu zakupu

Pole status aktualizacji zamówienia musi zawierać opis jego bieżącego stanu. W polu order.purchase.status aktualizacji użyj jednej z tych wartości:

  • CREATED – zamówienie jest zaakceptowane przez użytkownika i „utworzone” z perspektywy akcji, ale wymaga ręcznego przetworzenia przez backend.
  • CONFIRMED – zamówienie jest aktywne i trwa przetwarzanie w celu realizacji.
  • IN_PREPARATION – zamówienie jest przygotowywane do wysyłki/dostawy, np. gotowanie lub pakowanie przedmiotu.
  • READY_FOR_PICKUP – zamówienie może zostać odebrane przez odbiorcę.
  • DELIVERED – zamówienie zostało dostarczone do odbiorcy
  • OUT_OF_STOCK – co najmniej jeden produkt w zamówieniu jest niedostępny.
  • CHANGE_REQUESTED – użytkownik poprosił o zmianę zamówienia, która jest przetwarzana.
  • RETURNED – zamówienie zostało zwrócone przez użytkownika po dostawie.
  • REJECTED – jeśli nie udało Ci się przetworzyć, obciążyć lub w inny sposób „aktywować” zamówienia.
  • CANCELLED – zamówienie zostało anulowane przez użytkownika.

Musisz wysyłać aktualizacje zamówienia dla każdego stanu istotnego dla Twojej transakcji. Jeśli na przykład transakcja wymaga ręcznego przetworzenia w celu zarejestrowania zamówienia po jego złożeniu, wysyłaj aktualizację zamówienia CREATED do czasu zakończenia dodatkowego przetwarzania. Nie każde zamówienie wymaga podania wartości stanu.

Testowanie projektu

Podczas testowania projektu możesz włączyć tryb piaskownicy w Konsoli Actions, aby testować akcję bez obciążania formy płatności. Aby włączyć tryb piaskownicy, wykonaj te czynności:

  1. W panelu nawigacyjnym w Konsoli Actions kliknij Przetestuj.
  2. Kliknij Ustawienia.
  3. Włącz opcję Piaskownica dla programistów.

W przypadku transakcji fizycznych możesz też ustawić w polu isInSandbox wartość true w próbce. To działanie odpowiada włączeniu ustawienia trybu piaskownicy w konsoli Actions. Aby zobaczyć fragment kodu, który używa isInSandbox, zapoznaj się z sekcją Wysyłanie aktualizacji zamówień.

Rozwiązywanie problemów

Jeśli podczas testowania napotkasz jakieś problemy, przeczytaj nasze instrukcje rozwiązywania problemów z transakcjami.