Tạo giao dịch thực bằng Google Pay

Tài liệu hướng dẫn này sẽ trình bày quy trình phát triển một dự án Hành động có kết hợp các giao dịch mua hàng hoá thực và sử dụng Google Pay để thanh toán.

Luồng giao dịch

Khi dự án Hành động của bạn xử lý các giao dịch thực tế bằng các khoản thanh toán do người bán quản lý, dự án đó sẽ sử dụng quy trình sau:

  1. Thu thập thông tin (không bắt buộc) – Tuỳ thuộc vào bản chất giao dịch, bạn có thể cần thu thập thông tin sau từ người dùng khi bắt đầu cuộc trò chuyện:
    1. Xác thực các yêu cầu về giao dịch – Khi bắt đầu cuộc trò chuyện, hãy xác thực rằng người dùng đáp ứng các yêu cầu để thực hiện giao dịch, chẳng hạn như thiết lập và có sẵn thông tin thanh toán đúng cách trước khi tạo giỏ hàng.
    2. Yêu cầu địa chỉ giao hàng – Nếu giao dịch yêu cầu địa chỉ giao hàng, hãy thu thập một địa chỉ từ người dùng.
  2. Tạo đơn đặt hàng – Hướng dẫn người dùng thực hiện "tập hợp giỏ hàng" để chọn mặt hàng họ muốn mua.
  3. Đề xuất đơn đặt hàng – Sau khi hoàn tất giỏ hàng, hãy đề xuất đơn đặt hàng cho người dùng để họ có thể xác nhận đơn đặt hàng đó là chính xác. Nếu đơn đặt hàng được xác nhận, bạn sẽ nhận được phản hồi kèm theo thông tin chi tiết về đơn đặt hàng và mã thanh toán.
  4. Hoàn tất đơn đặt hàng và gửi biên nhận – Sau khi xác nhận đơn đặt hàng, hãy cập nhật tính năng theo dõi kho hàng hoặc các dịch vụ thực hiện khác của bạn rồi gửi biên nhận cho người dùng.
  5. Gửi thông tin cập nhật đơn đặt hàng – Trong suốt thời gian thực hiện đơn đặt hàng, hãy cung cấp thông tin cập nhật đơn đặt hàng của người dùng bằng cách gửi yêu cầu PATCH đến API đơn đặt hàng.

Các quy định hạn chế và nguyên tắc về bài đánh giá

Xin lưu ý rằng các chính sách bổ sung áp dụng cho Hành động có giao dịch. Chúng tôi có thể mất đến 6 tuần để xem xét các Hành động có giao dịch. Vì vậy, hãy tính đến thời gian đó khi lên kế hoạch cho lịch phát hành. Để quá trình xem xét diễn ra dễ dàng, hãy đảm bảo bạn tuân thủ các chính sách và nguyên tắc về giao dịch trước khi gửi Hành động đi xem xét.

Bạn chỉ có thể triển khai Hành động bán hàng hoá thực ở những quốc gia sau đây:

Úc
Brazil
Canada
Indonesia
Nhật Bản
Mexico
Nga
Singapore
Thái Lan
Thổ Nhĩ Kỳ
Vương quốc Anh
Hoa Kỳ

Xây dựng dự án của bạn

Để biết ví dụ bao quát về các cuộc trò chuyện giao dịch, hãy xem mẫu giao dịch của Node.js.

Thiết lập

Khi tạo Hành động, bạn phải chỉ định rằng bạn muốn thực hiện giao dịch trong Bảng điều khiển Actions.

Để thiết lập dự án và phương thức thực hiện, hãy làm như sau:

  1. Tạo dự án mới hoặc nhập dự án hiện có.
  2. Chuyển đến phần Triển khai > Thông tin thư mục.
  3. Trong phần Thông tin bổ sung > Giao dịch >, hãy đánh dấu hộp có nội dung "Hành động của bạn có sử dụng API Giao dịch để thực hiện các giao dịch đối với hàng hoá thực không?".

1. Thu thập thông tin (không bắt buộc)

1a. Xác thực các yêu cầu về giao dịch (không bắt buộc)

Ngay khi người dùng cho biết họ muốn mua hàng, bạn nên kiểm tra để đảm bảo rằng họ có thể thực hiện giao dịch. Ví dụ: khi được gọi, Hành động của bạn có thể hỏi "bạn muốn đặt giày hay kiểm tra số dư tài khoản của bạn?" Nếu người dùng nói "đặt giày", bạn phải đảm bảo rằng họ có thể tiếp tục và cho họ cơ hội khắc phục mọi chế độ cài đặt ngăn họ tiếp tục giao dịch. Để thực hiện việc này, bạn nên chuyển sang một cảnh kiểm tra các yêu cầu về giao dịch.

Tạo yêu cầu đối với giao dịch Kiểm tra cảnh
  1. Trên thẻ Cảnh, hãy thêm một Cảnh mới có tên TransactionRequirementsCheck.
  2. Trong mục Lấp đầy khe, hãy nhấp vào dấu + để thêm một vùng mới.
  3. Trong mục Chọn loại, hãy chọn actions.type.TransactionRequirementsCheckResult làm loại vùng.
  4. Trong trường tên khe, hãy đặt tên cho vị trí là TransactionRequirementsCheck.
  5. Bật hộp đánh dấu Tuỳ chỉnh ghi lại giá trị vị trí (bật theo mặc định).
  6. Nhấp vào Lưu.

Quy trình kiểm tra yêu cầu đối với giao dịch sẽ dẫn đến một trong các kết quả sau:

  • Nếu các yêu cầu được đáp ứng, thông số phiên sẽ được đặt với điều kiện thành công và bạn có thể tiếp tục tạo đơn đặt hàng của người dùng.
  • Nếu không thể đáp ứng một hoặc nhiều yêu cầu, thông số phiên sẽ được đặt bằng một điều kiện lỗi. Trong trường hợp này, bạn nên chuyển cuộc trò chuyện khỏi trải nghiệm giao dịch hoặc kết thúc cuộc trò chuyện.
    • Nếu người dùng có thể khắc phục bất kỳ lỗi nào dẫn đến trạng thái lỗi, họ sẽ được nhắc khắc phục các vấn đề đó trên thiết bị. Nếu cuộc trò chuyện diễn ra trên một nền tảng chỉ có giọng nói, thì điện thoại của người dùng sẽ được chuyển giao.

Xử lý kết quả kiểm tra các yêu cầu đối với giao dịch

  1. Trên thẻ Scenes (Cảnh), hãy chọn cảnh TransactionRequirementsCheck mới tạo.
  2. Trong mục Điều kiện, hãy nhấp vào dấu + để thêm một điều kiện mới.
  3. Trong trường văn bản, hãy nhập cú pháp điều kiện sau để kiểm tra điều kiện thành công:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
    
  4. Di chuột qua điều kiện bạn vừa thêm rồi nhấp vào mũi tên lên để đặt điều kiện đó trước if scene.slots.status == "FINAL".

  5. Bật tính năng Gửi lời nhắc và cung cấp một lời nhắc đơn giản cho người dùng biết rằng họ đã sẵn sàng thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase physical goods.
    
  6. Trong phần Transition (Chuyển đổi), hãy chọn một cảnh khác, cho phép người dùng tiếp tục cuộc trò chuyện và thực hiện giao dịch.

  7. Chọn điều kiện else if scene.slots.status == "FINAL".

  8. Bật tính năng Gửi lời nhắc và đưa ra một lời nhắc đơn giản cho người dùng biết rằng họ không thể thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: Transaction requirements check failed.
    
  9. Trong phần Chuyển đổi, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện nếu người dùng không thể thực hiện giao dịch.

Yêu cầu địa chỉ giao hàng

Nếu giao dịch của bạn yêu cầu địa chỉ giao hàng của người dùng, bạn nên yêu cầu người dùng cung cấp địa chỉ đó. Việc này có thể hữu ích khi bạn xác định tổng giá, vị trí giao hàng/nhận hàng hoặc đảm bảo người dùng ở trong khu vực kinh doanh của bạn. Để làm như vậy, bạn nên chuyển sang cảnh nhắc người dùng cung cấp địa chỉ giao hàng của họ.

Tạo cảnh địa chỉ giao hàng

  1. Trên thẻ Scenes (Cảnh), hãy thêm một cảnh mới có tên DeliveryAddress.
  2. Trong mục Lấp đầy khe, hãy nhấp vào dấu + để thêm một vùng mới.
  3. Trong Chọn loại, hãy chọn actions.type.DeliveryAddressValue làm loại vùng.
  4. Trong trường tên khe, hãy đặt tên cho vị trí là TransactionDeliveryAddress.
  5. Bật hộp kiểm Tùy chỉnh ghi lại giá trị vị trí (được bật theo mặc định).
  6. Nhấp vào Lưu.

Khi định cấu hình vị trí, bạn có thể cung cấp reason để có thể mở đầu yêu cầu của Trợ lý để lấy địa chỉ có chuỗi.Chuỗi lý do mặc định là "để biết nơi gửi đơn đặt hàng". Do đó, Trợ lý có thể hỏi người dùng: "Để biết nơi gửi đơn đặt hàng, tôi cần biết địa chỉ giao hàng của bạn".

  • Trên các nền tảng có màn hình, người dùng sẽ chọn địa chỉ họ muốn sử dụng cho giao dịch. Nếu trước đây chưa cung cấp địa chỉ, họ có thể nhập một địa chỉ mới.
  • Trên các nền tảng chỉ có giọng nói, Trợ lý sẽ yêu cầu người dùng cấp quyền chia sẻ địa chỉ mặc định của họ cho giao dịch. Nếu trước đó họ chưa cung cấp địa chỉ, cuộc trò chuyện sẽ được chuyển đến điện thoại để vào.

Để xử lý kết quả Địa chỉ giao hàng, hãy làm theo các bước sau:

  1. Trên thẻ Cảnh, hãy chọn cảnh bạn mới tạo DeliveryAddress.
  2. Trong mục Điều kiện, hãy nhấp vào dấu + để thêm một điều kiện mới.
  3. Trong trường văn bản, hãy nhập cú pháp điều kiện sau để kiểm tra điều kiện thành công:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
    
  4. Di chuột qua điều kiện bạn vừa thêm rồi nhấp vào mũi tên lên để đặt điều kiện đó trước if scene.slots.status == "FINAL".

  5. Bật tính năng Gửi lời nhắc và cung cấp một lời nhắc đơn giản để người dùng biết bạn đã nhận được địa chỉ của họ:

    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. Trong Chuyển đổi, chọn một cảnh khác, cho phép người dùng tiếp tục cuộc trò chuyện.

  7. Chọn điều kiện else if scene.slots.status == "FINAL".

  8. Bật tính năng Gửi lời nhắc và đưa ra một lời nhắc đơn giản cho người dùng biết rằng họ không thể thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: I failed to get your delivery address.
    
  9. Trong phần Chuyển đổi, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện nếu người dùng không thể thực hiện giao dịch.

Tạo đơn đặt hàng

Sau khi có thông tin người dùng cần thiết, bạn sẽ xây dựng trải nghiệm "tập hợp giỏ hàng" để hướng dẫn người dùng tạo đơn đặt hàng. Mỗi Hành động sẽ có quy trình tập hợp giỏ hàng hơi khác một chút, phù hợp với sản phẩm hoặc dịch vụ tương ứng.

Trải nghiệm tập hợp giỏ hàng cơ bản nhất là người dùng chọn các mặt hàng trong danh sách để thêm vào đơn đặt hàng, mặc dù bạn có thể thiết kế cuộc trò chuyện để đơn giản hoá trải nghiệm người dùng. Bạn có thể xây dựng trải nghiệm tập hợp giỏ hàng cho phép người dùng đặt hàng lại giao dịch mua gần đây nhất của họ thông qua câu hỏi đơn giản có hoặc không. Bạn cũng có thể hiển thị cho người dùng băng chuyền hoặc thẻ danh sách gồm các mục "nổi bật" hoặc "được đề xuất" hàng đầu.

Bạn nên sử dụng phản hồi đa dạng thức để trình bày trực quan các lựa chọn của người dùng, đồng thời thiết kế cuộc trò chuyện để người dùng có thể tạo giỏ hàng chỉ bằng giọng nói. Để biết một số phương pháp hay nhất và ví dụ về trải nghiệm tập hợp giỏ hàng chất lượng cao, hãy xem Nguyên tắc thiết kế.

Tạo đơn đặt hàng

Trong suốt cuộc trò chuyện, bạn sẽ cần thu thập các mặt hàng mà người dùng muốn mua, sau đó tạo một đối tượng Order.

Ở mức tối thiểu, Order của bạn phải có:

  • buyerInfo – Thông tin về người dùng mua hàng.
  • transactionMerchant – Thông tin về người bán hỗ trợ đơn đặt hàng.
  • contents – Nội dung thực tế của đơn đặt hàng được liệt kê là lineItems.
  • priceAttributes – Thông tin chi tiết về giá của đơn đặt hàng, bao gồm tổng chi phí của đơn đặt hàng (đã bao gồm các khoản chiết khấu và thuế).

Tham khảo tài liệu về phản hồi Order để tạo giỏ hàng. Xin lưu ý rằng bạn có thể cần bao gồm các trường khác nhau tuỳ thuộc vào thứ tự.

Mã mẫu dưới đây cho thấy một đơn đặt hàng hoàn chỉnh, bao gồm cả các trường không bắt buộc:

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

Tạo các tuỳ chọn thứ tự và trình bày

Trước khi người dùng xác nhận đơn đặt hàng, họ sẽ thấy một thẻ đơn đặt hàng được đề xuất. Bạn có thể tuỳ chỉnh cách trình bày thẻ này cho người dùng bằng cách đặt nhiều tuỳ chọn về thứ tự và cách trình bày.

Dưới đây là các lựa chọn đặt hàng và trình bày để khách hàng có thể đặt hàng yêu cầu địa chỉ giao hàng, bao gồm cả email của người dùng trong thẻ xác nhận đơn đặt hàng:

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

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

Tạo thông số thanh toán

Đối tượng paymentParameters sẽ bao gồm các thông số mã hoá. Các thông số này sẽ thay đổi tuỳ thuộc vào trình xử lý của Google Pay mà bạn dự định sử dụng (chẳng hạn như Stripe, Braintree, ACI, v.v.).

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

Nội dung của đối tượng tokenizationSpecification sẽ khác nhau đối với mỗi cổng thanh toán. Bảng sau đây trình bày các tham số mà mỗi cổng vào sử dụng:

VÍ DỤ
"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"
}
BÓNG ĐÁ
"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"
}
Thanh toán
"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"
}
HIỆN TẠI
"parameters": {
  "gateway": "hitrustpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
GIẢI PHÁP GIẢI PHÁP
"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"
}
SPACE_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 (NMI)
"parameters": {
  "gateway": "creditcall",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
PAYAN
"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"
}
RBKCURRENCY
"parameters": {
  "gateway": "rbkmoney",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}
SBERBANK
"parameters": {
  "gateway": "sberbank",
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
}
BÌNH LUẬN
"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"
}

Lưu dữ liệu đơn đặt hàng trong tham số phiên

Từ phương thức thực hiện đơn hàng, hãy lưu dữ liệu đơn đặt hàng vào tham số phiên hoạt động. Đối tượng thứ tự sẽ được dùng trên các cảnh trong cùng một phiên hoạt động.

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

Đề xuất đơn đặt hàng

Sau khi tạo đơn đặt hàng, bạn phải đưa ra cho người dùng để xác nhận hoặc từ chối. Để làm như vậy, bạn nên chuyển sang cảnh thực hiện quyết định giao dịch.

Tạo cảnh Quyết định giao dịch

  1. Trên thẻ Scenes (Cảnh), hãy thêm một cảnh mới có tên TransactionDecision.
  2. Trong mục Lấp đầy khe, hãy nhấp vào dấu + để thêm một vùng mới.
  3. Trong mục Chọn loại, hãy chọn actions.type.TransactionDecisionValue làm loại vùng.
  4. Trong trường tên khe, hãy đặt tên cho vị trí là TransactionDecision.
  5. Bật hộp kiểm Tùy chỉnh ghi lại giá trị vị trí (được bật theo mặc định).
  6. Trong mục Định cấu hình vị trí, hãy chọn Sử dụng tham số phiên trên trình đơn thả xuống.
  7. Trong mục Định cấu hình khe,hãy nhập tên của tham số phiên được dùng để lưu trữ đơn đặt hàng vào trường văn bản (tức là $session.params.order).
  8. Nhấp vào Lưu.

Để lấp đầy một vị trí TransactionDecisionValue, Trợ lý sẽ bắt đầu một trải nghiệm tích hợp, trong đó Order bạn đã chuyển sẽ hiển thị trực tiếp vào "thẻ xem trước giỏ hàng". Người dùng có thể nói "đặt hàng", từ chối giao dịch, thay đổi một lựa chọn thanh toán như thẻ tín dụng hay địa chỉ hoặc yêu cầu thay đổi nội dung của đơn đặt hàng.

Người dùng cũng có thể yêu cầu thay đổi đơn đặt hàng tại thời điểm này. Trong trường hợp này, bạn nên đảm bảo phương thức thực hiện của mình có thể xử lý các yêu cầu thay đổi đơn đặt hàng sau khi hoàn tất trải nghiệm lắp ráp giỏ hàng.

Xử lý kết quả Quyết định giao dịch

Khi một vị trí TransactionDecisionValue được lấp đầy, câu trả lời của người dùng về quyết định giao dịch sẽ được lưu trữ trong thông số phiên. Giá trị này chứa:

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

Cách xử lý kết quả quyết định về giao dịch:

  1. Trên thẻ Cảnh, hãy chọn cảnh bạn mới tạo TransactionDecision.
  2. Trong mục Điều kiện, hãy nhấp vào dấu + để thêm một điều kiện mới.
  3. Trong trường văn bản, hãy nhập cú pháp điều kiện sau để kiểm tra điều kiện thành công:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  4. Di chuột qua điều kiện bạn vừa thêm rồi nhấp vào mũi tên lên để đặt điều kiện đó trước if scene.slots.status == "FINAL".

  5. Bật tính năng Gửi lời nhắc và cung cấp một lời nhắc đơn giản cho người dùng biết rằng đơn đặt hàng của họ đã hoàn tất:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction completed! Your order
                $session.params.TransactionDecision.order.merchantOrderId is all
                set!
    
  6. Trong phần Chuyển đổi, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện.

  7. Trong mục Điều kiện, hãy nhấp vào dấu + để thêm một điều kiện mới.

  8. Trong trường văn bản, hãy nhập cú pháp điều kiện sau để kiểm tra các điều kiện không đạt:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
    
  9. Di chuột qua điều kiện bạn vừa thêm rồi nhấp vào mũi tên lên để đặt điều kiện đó trước if scene.slots.status == "FINAL".

  10. Bật tính năng Gửi lời nhắc và cung cấp một lời nhắc đơn giản cho người dùng biết rằng đơn đặt hàng đã bị từ chối:

    candidates:
      - first_simple:
          variants:
            - speech: Look like you don't want to order anything. Goodbye.
    
  11. Trong phần Chuyển tiếp, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện.

  12. Chọn điều kiện else if scene.slots.status == "FINAL".

  13. Bật tính năng Gửi lời nhắc và cung cấp một lời nhắc đơn giản cho người dùng biết rằng họ không thể thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction failed with status
                $session.params.TransactionDecision.transactionDecision
    
  14. Trong phần Chuyển đổi, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện nếu người dùng không thể thực hiện giao dịch.

Hoàn tất đơn đặt hàng và gửi biên nhận

Khi khe TransactionDecisionValue trả về kết quả là ORDER_ACCEPTED, bạn phải ngay lập tức thực hiện mọi quá trình xử lý cần thiết để "xác nhận" thứ tự (chẳng hạn như lưu giữ kết quả trong cơ sở dữ liệu của riêng mình và tính phí cho người dùng).

Bạn có thể kết thúc cuộc trò chuyện bằng phản hồi này nhưng phải đưa ra một câu trả lời đơn giản để tiếp tục duy trì cuộc trò chuyện. Khi bạn cung cấp orderUpdate ban đầu này, người dùng sẽ thấy một "thẻ biên nhận đã thu gọn" cùng với phần còn lại của phản hồi. Thẻ này sẽ phản ánh biên nhận mà người dùng thấy trong Nhật ký đặt hàng của họ.

Trong quá trình xác nhận đơn đặt hàng, đối tượng đơn đặt hàng của bạn có thể bao gồm userVisibleOrderId, là mã mà người dùng nhìn thấy cho đơn đặt hàng. Bạn có thể sử dụng lại merchantOrderId cho trường này.

Một phần của đối tượng OrderUpdate sẽ cần chứa một đối tượng hành động tiếp theo. Đối tượng này sẽ xuất hiện dưới dạng các nút URL ở cuối phần chi tiết đơn đặt hàng mà người dùng có thể tìm thấy trong Nhật ký đặt hàng trên Trợ lý.

  • Tối thiểu, bạn phải cung cấp một Hành động tiếp theo VIEW_DETAILS đối với từng đơn đặt hàng. Thuộc tính này phải chứa một đường liên kết sâu đến nội dung trình bày đơn đặt hàng trên ứng dụng dành cho thiết bị di động hoặc trang web của bạn.
  • Ngoài thẻ biên nhận, bạn cũng phải gửi qua email biên nhận chính thức đáp ứng tất cả yêu cầu pháp lý để tiến hành giao dịch, trong cuộc trò chuyện với Hành động của bạn.

Cách gửi thông tin cập nhật về đơn đặt hàng ban đầu:

  1. Trên thẻ Scenes (Cảnh), hãy chọn cảnh TransactionDecision của bạn.
  2. Trong phần Điều kiện, hãy chọn điều kiện kiểm tra kết quả thành công, ORDER_ACCEPTED:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  3. Đối với điều kiện này, hãy bật Gọi webhook và cung cấp tên trình xử lý ý định, chẳng hạn như update_order.

  4. Trong mã webhook, hãy thêm một trình xử lý ý định để gửi thông tin cập nhật đơn đặt hàng ban đầu:

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

Gửi thông tin cập nhật về đơn đặt hàng

Bạn sẽ cần thông báo cho người dùng về trạng thái của đơn đặt hàng trong suốt vòng đời của đơn đặt hàng đó. Gửi thông tin cập nhật về đơn đặt hàng của người dùng bằng cách gửi yêu cầu PATCH HTTP tới API đơn đặt hàng cùng với trạng thái và thông tin chi tiết về đơn đặt hàng.

Thiết lập các yêu cầu không đồng bộ cho API đơn đặt hàng

Các yêu cầu cập nhật đơn đặt hàng đối với API Đơn đặt hàng được uỷ quyền bằng một mã truy cập. Để PATCH cập nhật đơn đặt hàng lên API đơn đặt hàng, hãy tải khoá tài khoản dịch vụ JSON liên kết với dự án Actions Console của bạn, sau đó đổi khoá tài khoản dịch vụ lấy mã thông báo truy cập có thể được truyền vào tiêu đề Authorization của yêu cầu HTTP.

Để truy xuất khoá tài khoản dịch vụ của bạn, hãy thực hiện các bước sau:

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn STDEV > API và Dịch vụ > Thông tin xác thực > Tạo thông tin xác thực > Khoá tài khoản dịch vụ.
  2. Trong phần Tài khoản dịch vụ, hãy chọn Tài khoản dịch vụ mới.
  3. Đặt tài khoản dịch vụ thành service-account.
  4. Đặt Role thành Project > Owner (Dự án > Chủ sở hữu).
  5. Đặt loại khoá thành JSON.
  6. Chọn Tạo.
  7. Khoá tài khoản dịch vụ JSON riêng tư sẽ được tải xuống máy cục bộ của bạn.

Trong mã cập nhật đơn đặt hàng, bạn có thể đổi khoá dịch vụ để lấy mã thông báo truy cập bằng cách sử dụng thư viện ứng dụng API của Google và phạm vi "https://www.googleapis.com/auth/actions.order.developer". Bạn có thể tìm thấy các bước cài đặt và ví dụ trên trang GitHub trong thư viện ứng dụng API.

Bạn cũng có thể tham khảo order-update.js trong mẫu Node.js của chúng tôi để biết ví dụ về trao đổi khoá.

Gửi thông tin cập nhật về đơn đặt hàng

Sau khi đổi khoá tài khoản dịch vụ của mình để lấy mã thông báo truy cập OAuth, bạn có thể gửi thông tin cập nhật đơn đặt hàng dưới dạng các yêu cầu PATCH được uỷ quyền tới API đơn đặt hàng.

URL của API Đơn đặt hàng: PATCH https://actions.googleapis.com/v3/orders/${orderId}

Cung cấp các tiêu đề sau trong yêu cầu của bạn:

  • "Authorization: Bearer token" bằng mã thông báo truy cập OAuth mà bạn đã đổi khoá tài khoản dịch vụ của mình.
  • "Content-Type: application/json".

Yêu cầu PATCH phải có nội dung JSON có định dạng sau:

{ "orderUpdate": OrderUpdate }

Đối tượng OrderUpdate bao gồm các trường cấp cao nhất sau đây:

  • updateMask – Các trường của đơn đặt hàng bạn đang cập nhật. Để cập nhật trạng thái đơn đặt hàng, hãy đặt giá trị thành purchase.status, purchase.userVisibleStatusLabel.
  • order – Nội dung của bản cập nhật. Nếu bạn đang cập nhật nội dung của đơn đặt hàng, hãy đặt giá trị thành đối tượng Order đã cập nhật. Nếu bạn đang cập nhật trạng thái của đơn đặt hàng (ví dụ: từ "CONFIRMED" thành "SHIPPED"), thì đối tượng sẽ chứa các trường sau:

    • merchantOrderId – Mã nhận dạng mà bạn đã đặt cho đối tượng Order.
    • lastUpdateTime – Dấu thời gian của lần cập nhật này.
    • purchase – Đối tượng chứa:
      • status – Trạng thái của đơn đặt hàng dưới dạng PurchaseStatus, chẳng hạn như "SHIPPED" hoặc "DELIVERED".
      • userVisibleStatusLabel – Một nhãn dành cho người dùng, cung cấp thông tin chi tiết về trạng thái đơn đặt hàng, chẳng hạn như "Đơn đặt hàng của bạn đã được vận chuyển và đang trên đường vận chuyển".
  • userNotification có thể hiển thị trên thiết bị của người dùng khi bản cập nhật này được gửi. Xin lưu ý rằng việc thêm đối tượng này không đảm bảo rằng thông báo sẽ xuất hiện trên thiết bị của người dùng.

Mã mẫu sau đây minh hoạ một OrderUpdate mẫu cập nhật trạng thái của đơn đặt hàng thành 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}`);
}
Đặt trạng thái mua hàng

status của bản cập nhật đơn đặt hàng phải mô tả trạng thái hiện tại của đơn đặt hàng. Trong trường order.purchase.status của bản cập nhật, hãy dùng một trong những giá trị sau:

  • CREATED – Đơn đặt hàng được người dùng chấp nhận và "được tạo" từ góc độ Hành động của bạn nhưng cần phải xử lý thủ công trên máy chủ phụ trợ.
  • CONFIRMED – Đơn đặt hàng đang hoạt động và đang được xử lý để thực hiện đơn hàng.
  • IN_PREPARATION – Đơn đặt hàng đang được chuẩn bị để vận chuyển/giao hàng, chẳng hạn như thức ăn đang nấu hoặc một mặt hàng đang đóng gói.
  • READY_FOR_PICKUP - Người nhận có thể đến lấy đơn đặt hàng.
  • DELIVERED - Đơn đặt hàng đã được giao tới người nhận
  • OUT_OF_STOCK – Một hoặc nhiều mặt hàng trong đơn đặt hàng đã hết hàng.
  • CHANGE_REQUESTED – Người dùng đã yêu cầu thay đổi đơn đặt hàng và thay đổi đó đang được xử lý.
  • RETURNED – Người dùng trả lại đơn đặt hàng sau khi giao hàng.
  • REJECTED – Nếu bạn không thể xử lý, tính phí hoặc "kích hoạt" đơn đặt hàng.
  • CANCELLED – Người dùng đã huỷ đơn đặt hàng.

Bạn nên gửi thông tin cập nhật về đơn đặt hàng cho từng trạng thái liên quan đến giao dịch của mình. Ví dụ: nếu giao dịch của bạn yêu cầu xử lý thủ công để ghi nhật ký đơn đặt hàng sau khi đặt, hãy gửi thông tin cập nhật đơn đặt hàng CREATED cho đến khi quá trình xử lý bổ sung đó hoàn tất. Không phải đơn đặt hàng nào cũng yêu cầu tất cả giá trị trạng thái.

Kiểm thử dự án

Khi kiểm thử dự án, bạn có thể bật chế độ hộp cát trong bảng điều khiển Actions để kiểm thử Hành động của mình mà không tính phí cho phương thức thanh toán. Để bật chế độ hộp cát, hãy làm theo các bước sau:

  1. Trong bảng điều khiển Actions, hãy nhấp vào Test (Kiểm thử) trong bảng điều hướng.
  2. Nhấp vào Cài đặt.
  3. Bật tuỳ chọn Phát triển Hộp cát.

Đối với các giao dịch thực tế, bạn cũng có thể đặt trường isInSandbox thành true trong mẫu. Thao tác này tương đương với việc bật tuỳ chọn cài đặt chế độ hộp cát trong bảng điều khiển Actions. Để xem đoạn mã sử dụng isInSandbox, hãy xem phần Gửi thông tin cập nhật về đơn đặt hàng.

Khắc phục sự cố

Nếu gặp vấn đề nào trong quá trình kiểm thử, bạn nên đọc các bước khắc phục sự cố của chúng tôi để biết các giao dịch.