Membuat transaksi fisik dengan Google Pay

Panduan ini akan memandu Anda dalam proses pengembangan project Actions yang menggabungkan transaksi untuk barang fisik dan menggunakan Google Pay untuk pembayaran.

Alur transaksi

Saat project Actions Anda menangani transaksi fisik menggunakan pembayaran yang dikelola penjual, project tersebut menggunakan alur berikut:

  1. Kumpulkan informasi (opsional) - Bergantung pada sifat transaksi, Anda dapat mengumpulkan informasi berikut dari pengguna di awal percakapan:
    1. Validasi persyaratan transaksi - Pada awal percakapan, validasi bahwa pengguna memenuhi persyaratan untuk melakukan transaksi, seperti mengonfigurasi informasi pembayaran dengan benar dan tersedia sebelum membuat keranjang.
    2. Minta alamat pengiriman - Jika transaksi memerlukan alamat pengiriman, kumpulkan dari pengguna.
  2. Membuat pesanan - Arahkan pengguna melalui "perakitan keranjang" tempat mereka memilih item yang ingin dibeli.
  3. Mengusulkan pesanan - Setelah keranjang selesai diproses, ajukan pesanan kepada pengguna agar mereka dapat mengonfirmasi bahwa pesanan sudah benar. Jika pesanan dikonfirmasi, Anda akan menerima respons dengan detail pesanan dan token pembayaran.
  4. Menyelesaikan pesanan dan mengirim tanda terima - Setelah pesanan dikonfirmasi, perbarui pelacakan inventaris atau layanan pemenuhan lainnya, lalu kirim tanda terima kepada pengguna.
  5. Kirim pembaruan pesanan - Selama masa aktif pemenuhan pesanan, berikan pembaruan pesanan pengguna dengan mengirimkan permintaan PATCH ke Orders API.

Panduan pembatasan dan peninjauan

Perlu diingat bahwa kebijakan tambahan berlaku untuk Tindakan dengan transaksi. Kami memerlukan waktu hingga enam minggu untuk meninjau Tindakan dengan transaksi, jadi pertimbangkan waktu tersebut saat merencanakan jadwal rilis Anda. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan dan pedoman untuk transaksi sebelum mengirimkan Action untuk ditinjau.

Anda hanya dapat men-deploy Action yang menjual barang fisik di negara berikut:

Australia
Brasil
Kanada
Indonesia 		Jepang
Meksiko
Rusia 		Singapura
Thailand
Turki
Inggris Raya
Amerika Serikat

Mem-build project Anda

Untuk contoh ekstensif transaksi transaksional, lihat contoh transaksi Node.js.

Penyiapan

Saat membuat Action, Anda harus menentukan bahwa Anda ingin melakukan transaksi di konsol Actions.

Untuk menyiapkan project dan fulfillment, lakukan hal berikut:

  1. Buat project baru, atau impor project yang sudah ada.
  2. Buka Deploy > Directory information.

  3. Di bagian Informasi tambahan > Transaksi > centang kotak yang bertuliskan "Apakah Tindakan Anda menggunakan Transactions API untuk melakukan transaksi barang fisik?".

1. Mengumpulkan informasi (opsional)

1a. Memvalidasi persyaratan transaksi (opsional)

Segera setelah pengguna mengindikasikan bahwa mereka ingin melakukan pembelian, Anda harus memeriksa untuk memastikan bahwa mereka dapat melakukan transaksi. Misalnya, saat dipanggil,Action Anda mungkin bertanya, "apakah Anda ingin memesan sepatu, atau memeriksa saldo rekening Anda?" Jika pengguna mengatakan "pesan sepatu", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberi mereka kesempatan untuk memperbaiki setelan yang mencegah mereka melanjutkan transaksi. Untuk melakukannya, Anda harus beralih ke scene yang melakukan pemeriksaan persyaratan transaksi.

Membuat scene Pemeriksaan Persyaratan Transaksi
  1. Dari tab Scenes, tambahkan Scene baru dengan nama TransactionRequirementsCheck.
  2. Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.TransactionRequirementsCheckResult sebagai jenis slot.
  4. Di kolom nama slot, berikan nama TransactionRequirementsCheck untuk slot.
  5. Centang kotak Sesuaikan penulisan nilai slot (diaktifkan secara default).
  6. Klik Simpan.

Pemeriksaan persyaratan transaksi akan menghasilkan salah satu hasil berikut:

  • Jika persyaratan terpenuhi, parameter sesi ditetapkan dengan kondisi yang berhasil dan Anda dapat melanjutkan dengan membuat pesanan pengguna.
  • Jika satu atau beberapa persyaratan tidak dapat dipenuhi, parameter sesi ditetapkan dengan kondisi kegagalan. Dalam hal ini, Anda harus mengalihkan percakapan dari pengalaman transaksi, atau mengakhiri percakapan.
    • Jika error yang mengakibatkan status kegagalan dapat diperbaiki oleh pengguna, error tersebut akan diminta untuk menyelesaikan masalah tersebut di perangkatnya. Jika percakapan berlangsung di platform suara saja, handoff akan dimulai ke ponsel pengguna.

Menangani hasil Pemeriksaan Persyaratan Transaksi

  1. Dari tab Scenes, pilih scene TransactionRequirementsCheck yang baru dibuat.
  2. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  3. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi sukses:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

  4. Arahkan kursor ke kondisi yang baru saja ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. Aktifkan Send prompt dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka siap melakukan transaksi:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase physical goods.

  6. Di bagian Transition, pilih scene lain, yang memungkinkan pengguna melanjutkan percakapan dan melanjutkan dengan melakukan transaksi.

  7. Pilih kondisi else if scene.slots.status == "FINAL".

  8. Aktifkan Send prompt dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka tidak dapat melakukan transaksi:

    candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.

  9. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Meminta alamat pengiriman

Jika transaksi memerlukan alamat pengiriman pengguna, Anda harus memintanya dari pengguna. Hal ini mungkin berguna untuk menentukan harga total, lokasi pengiriman/pengambilan, atau untuk memastikan pengguna berada dalam wilayah layanan Anda. Untuk melakukannya, Anda harus beralih ke scene yang meminta pengguna ke alamat pengiriman mereka.

Membuat Adegan Alamat Pengiriman

  1. Dari tab Scenes, tambahkan scene baru dengan nama DeliveryAddress.
  2. Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.DeliveryAddressValue sebagai jenis slot.
  4. Di kolom nama slot, berikan nama TransactionDeliveryAddress untuk slot.
  5. Aktifkan kotak centang Sesuaikan nilai slot kembali (diaktifkan secara default).
  6. Klik Simpan.

Saat mengonfigurasi slot, Anda dapat memberikan reason yang memungkinkan Anda memulai permintaan Asisten untuk mendapatkan alamat dengan string.String alasan defaultnya adalah "untuk mengetahui ke mana harus mengirim pesanan". Oleh karena itu, Asisten mungkin bertanya kepada pengguna: "Untuk mengetahui tempat untuk mengirimkan pesanan, saya perlu mendapatkan alamat pengiriman Anda".

  • Di platform yang menampilkan layar, pengguna akan memilih alamat yang ingin digunakan untuk transaksi. Jika belum pernah memberikan alamat, mereka dapat memasukkan alamat baru.
  • Di platform khusus suara, Asisten akan meminta izin kepada pengguna untuk membagikan alamat default-nya untuk transaksi. Jika sebelumnya mereka tidak memberikan alamat, percakapan akan diserahkan ke ponsel untuk dimasukkan.

Untuk menangani hasil Alamat Pengiriman, ikuti langkah-langkah berikut:

  1. Dari tab Scenes, pilih scene DeliveryAddress yang baru dibuat.
  2. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  3. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi sukses:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"

  4. Arahkan kursor ke kondisi yang baru saja ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. Aktifkan Send prompt dan berikan perintah sederhana yang memberitahukan pengguna bahwa Anda telah menerima alamatnya:

    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. Di bagian Transition, pilih scene lain, yang memungkinkan pengguna melanjutkan percakapan.

  7. Pilih kondisi else if scene.slots.status == "FINAL".

  8. Aktifkan Send prompt dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka tidak dapat melakukan transaksi:

    candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.

  9. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Buat pesanan

Setelah memiliki informasi pengguna yang dibutuhkan, Anda akan mem-build pengalaman "perakitan keranjang" yang memandu pengguna untuk membuat pesanan. Setiap Action akan memiliki alur perakitan keranjang yang sedikit berbeda sesuai dengan produk atau layanannya.

Pengalaman perakitan keranjang yang paling dasar memiliki pengguna yang memilih item dari daftar untuk ditambahkan ke pesanan mereka, meskipun Anda dapat mendesain percakapan untuk menyederhanakan pengalaman pengguna. Anda dapat membangun pengalaman perakitan keranjang yang memungkinkan pengguna mengurutkan ulang pembelian terbaru melalui pertanyaan ya atau tidak. Anda juga dapat menampilkan carousel atau kartu daftar item unggulan "unggul" atau "direkomendasikan" kepada pengguna.

Sebaiknya gunakan respons lengkap untuk menampilkan opsi pengguna secara visual, tetapi juga mendesain percakapan sehingga pengguna dapat membuat keranjang mereka hanya dengan suaranya. Untuk beberapa praktik terbaik dan contoh pengalaman perakitan keranjang berkualitas tinggi, lihat Pedoman desain.

Membuat pesanan

Sepanjang percakapan, Anda harus mengumpulkan item yang ingin dibeli pengguna, lalu membuat objek Order.

Setidaknya, Order Anda harus berisi hal berikut:

  • buyerInfo - Informasi tentang pengguna yang melakukan pembelian.
  • transactionMerchant - Informasi tentang penjual yang memfasilitasi pesanan.
  • contents - Konten sebenarnya dari pesanan yang tercantum sebagai lineItems.
  • priceAttributes - Detail harga pesanan, termasuk total biaya pesanan dengan diskon dan pajak.

Lihat dokumentasi respons Order untuk membuat keranjang Anda. Perhatikan bahwa Anda mungkin perlu menyertakan kolom yang berbeda bergantung pada urutannya.

Kode contoh di bawah menunjukkan pesanan lengkap, termasuk kolom opsional:

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

Membuat opsi pesanan dan presentasi

Sebelum mengonfirmasi pesanan, pengguna akan melihat kartu pesanan yang diusulkan. Anda dapat menyesuaikan cara kartu ini ditampilkan kepada pengguna dengan menyetel berbagai opsi urutan dan presentasi.

Berikut adalah opsi pesanan dan penyajian untuk melakukan pemesanan yang membutuhkan alamat pengiriman, termasuk email pengguna di kartu konfirmasi pesanan:

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

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

Membuat parameter pembayaran

Objek paymentParameters Anda akan menyertakan parameter tokenisasi yang berubah, bergantung pada prosesor Google Pay yang akan Anda gunakan (seperti Stripe, Braintree, ACI, dll.).

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

Konten objek tokenizationSpecification akan berbeda untuk setiap gateway pembayaran. Tabel berikut menunjukkan parameter yang digunakan oleh setiap gateway:

CONTOH
"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"
}
TERTAWA
"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"
}
CHECKOUT
"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"
}
HITRUS
"parameters": {
  "gateway": "hitrustpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
DAMPAKNYA
"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"
}
Money_EMAIL_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"
}
BAYAR
"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"
}
KOTAK
"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}
JEDA
"parameters": {
  "gateway": "stripe",
  "stripe:version": "2018-10-31",
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
}
KETAMANAN
"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"
}

Menyimpan data pesanan di parameter sesi

Dari fulfillment Anda, simpan data pesanan ke parameter sesi. Objek pesan akan digunakan di seluruh scene untuk sesi yang sama.

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

Mengusulkan pesanan

Setelah membuat pesanan, Anda harus menampilkannya kepada pengguna untuk mengonfirmasi atau menolaknya. Untuk melakukannya, Anda harus beralih ke scene yang menjalankan keputusan transaksi.

Membuat scene Keputusan Transaksi

  1. Dari tab Scenes, tambahkan scene baru dengan nama TransactionDecision.
  2. Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.TransactionDecisionValue sebagai jenis slot.
  4. Di kolom nama slot, berikan nama TransactionDecision untuk slot.
  5. Aktifkan kotak centang Sesuaikan nilai slot kembali (diaktifkan secara default).
  6. Di bagian Configure slot, pilih Use session parameter dari dropdown.
  7. Di bagian Configure slot, masukkan nama parameter sesi yang digunakan untuk menyimpan pesanan ke dalam kolom teks (yaitu $session.params.order).
  8. Klik Simpan.

Dalam upaya untuk mengisi slot TransactionDecisionValue, Asisten memulai pengalaman bawaan di mana Order yang Anda teruskan dirender langsung ke "kartu pratinjau keranjang". Pengguna dapat mengucapkan "pesankan", tolak transaksi, ubah opsi pembayaran seperti kartu kredit atau alamat, atau minta untuk mengubah isi pesanan.

Pengguna juga dapat meminta perubahan pada pesanan untuk saat ini. Dalam hal ini, Anda harus memastikan fulfillment Anda dapat menangani permintaan perubahan pesanan setelah menyelesaikan pengalaman perakitan keranjang.

Menangani hasil Keputusan Transaksi

Saat slot TransactionDecisionValue terisi, jawaban pengguna untuk keputusan transaksi akan disimpan di parameter sesi. Nilai ini berisi hal berikut:

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

Untuk menangani hasil keputusan transaksi:

  1. Dari tab Scenes, pilih scene TransactionDecision yang baru dibuat.
  2. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  3. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi sukses:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

  4. Arahkan kursor ke kondisi yang baru saja ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. Aktifkan Send prompt dan berikan perintah sederhana yang memberitahukan pengguna bahwa pesanan mereka telah selesai:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your order
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

  6. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.

  7. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  8. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi gagal:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

  9. Arahkan kursor ke kondisi yang baru saja ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  10. Aktifkan Kirim perintah dan berikan perintah sederhana yang memberitahukan pengguna bahwa pesanan telah ditolak:

    candidates:
  - first_simple:
      variants:
        - speech: Look like you don't want to order anything. Goodbye.

  11. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.

  12. Pilih kondisi else if scene.slots.status == "FINAL".

  13. Aktifkan Send prompt dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka tidak dapat melakukan transaksi:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

  14. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Selesaikan pesanan dan kirim tanda terima

Saat slot TransactionDecisionValue menampilkan hasil ORDER_ACCEPTED, Anda harus segera melakukan pemrosesan apa pun yang diperlukan untuk "mengonfirmasi" pesanan (seperti mempertahankannya di database Anda sendiri dan menagih pengguna).

Anda dapat mengakhiri percakapan dengan respons ini, tetapi Anda harus menyertakan respons sederhana untuk membuat percakapan terus berjalan. Saat Anda memberikan orderUpdate awal ini, pengguna akan melihat "kartu tanda terima yang diciutkan" bersama dengan respons Anda yang lain. Kartu ini akan mencerminkan tanda terima yang ditemukan pengguna di Histori Pesanan.

Selama konfirmasi pesanan, objek pesanan Anda dapat menyertakan userVisibleOrderId, yaitu ID yang dilihat pengguna untuk pesanan tersebut. Anda dapat menggunakan kembali merchantOrderId untuk kolom ini.

Bagian dari objek OrderUpdate harus berisi objek tindakan tindak lanjut, yang manifes sebagai tombol URL di bagian bawah detail pesanan yang dapat ditemukan pengguna di Histori Pesanan Asistennya.

  • Minimal, Anda harus memberikan Tindakan Tindak Lanjut VIEW_DETAILS dengan setiap pesanan. Link ini harus berisi deep-link ke representasi pesanan di aplikasi seluler atau situs Anda.
  • Anda juga harus mengirim tanda terima resmi melalui email yang memenuhi semua persyaratan hukum untuk melakukan transaksi, selain kartu tanda terima dalam percakapan Action Anda.

Untuk mengirim pembaruan pesanan awal:

  1. Dari tab Scenes, pilih scene TransactionDecision.

  2. Di bagian Kondisi, pilih kondisi yang memeriksa hasil keberhasilan, ORDER_ACCEPTED:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

  3. Untuk kondisi ini, aktifkan Telepon webhook Anda, lalu berikan nama pengendali intent, seperti update_order.

  4. Dalam kode webhook Anda, tambahkan pengendali intent untuk mengirim pembaruan pesanan awal:

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

Mengirim pembaruan pesanan

Anda harus terus memberi tahu pengguna tentang status pesanan tersebut selama masa aktifnya. Kirimkan pembaruan pesanan pengguna dengan mengirimkan permintaan PATCH HTTP ke Orders API dengan status dan detail pesanan.

Menyiapkan permintaan asinkron ke Orders API

Permintaan pembaruan pesanan ke Orders API diotorisasi oleh token akses. Untuk PATCH pembaruan pesanan ke Orders API, download kunci akun layanan JSON yang terkait dengan project Konsol Tindakan, lalu tukar kunci akun layanan dengan token pemilik yang dapat diteruskan ke header Authorization permintaan HTTP.

Untuk mengambil kunci akun layanan Anda, lakukan langkah-langkah berikut:

  1. Di Google Cloud Console, buka Menu ☰ > API & Layanan > Kredensial > Buat kredensial > Kunci akun layanan.
  2. Pada Akun Layanan, pilih Akun Layanan Baru.
  3. Setel akun layanan ke service-account.
  4. Tetapkan Peran ke Project > Pemilik.
  5. Tetapkan jenis kunci ke JSON.
  6. Pilih Buat.
  7. Kunci akun layanan JSON pribadi akan didownload ke komputer lokal Anda.

Dalam kode pembaruan pesanan, Anda dapat menukar kunci layanan dengan token pemilik menggunakan library klien Google API dan cakupan "https://www.googleapis.com/auth/actions.order.developer". Anda dapat menemukan langkah-langkah penginstalan dan contoh di halaman GitHub library klien API.

Anda juga dapat melihat order-update.js dalam contoh Node.js kami untuk contoh pertukaran kunci.

Mengirim pembaruan pesanan

Setelah menukar kunci akun layanan dengan token pemilik OAuth, Anda dapat mengirim pembaruan pesanan sebagai permintaan PATCH yang diotorisasi ke Orders API.

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

Berikan header berikut dalam permintaan Anda:

  • "Authorization: Bearer token" dengan token pemilik OAuth yang Anda tukarkan dengan kunci akun layanan Anda.
  • "Content-Type: application/json".

Permintaan PATCH harus menggunakan isi JSON dengan format berikut:

{ "orderUpdate": OrderUpdate }

Objek OrderUpdate terdiri dari kolom level teratas berikut:

  • updateMask - Kolom pesanan yang Anda perbarui. Untuk memperbarui status pesanan, tetapkan nilai ke purchase.status, purchase.userVisibleStatusLabel.

  • order - Konten update. Jika Anda memperbarui konten pesanan, tetapkan nilai ke objek Order yang telah diupdate. Jika Anda memperbarui status pesanan (misalnya, dari "CONFIRMED" ke "SHIPPED"), objek akan berisi kolom berikut:

    • merchantOrderId - ID yang sama dengan yang Anda tetapkan di objek Order.
    • lastUpdateTime - Stempel waktu pembaruan ini.
    • purchase - Objek yang berisi hal berikut:
      • status - Status pesanan sebagai PurchaseStatus, seperti "SHIPPED" atau "DELIVERED".
      • userVisibleStatusLabel - Label yang ditampilkan kepada pengguna, yang berisi detail status pesanan, seperti "Pesanan Anda telah dikirim dan sedang dalam proses".

  • userNotification (opsional) - Objek userNotification yang dapat ditampilkan pada perangkat pengguna saat update ini dikirim. Perlu diperhatikan bahwa menyertakan objek ini tidak menjamin bahwa notifikasi akan muncul di perangkat pengguna.

Kode contoh berikut menunjukkan contoh OrderUpdate yang memperbarui status pesanan menjadi 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}`);
}
Menetapkan status pembelian

status update pesanan harus menjelaskan status pesanan saat ini. Pada kolom order.purchase.status update, gunakan salah satu nilai berikut:

  • CREATED - Pesanan diterima oleh pengguna dan "dibuat" dari perspektif Action Anda, tetapi memerlukan pemrosesan manual di back-end.
  • CONFIRMED - Pesanan aktif dan sedang diproses untuk pemenuhan.
  • IN_PREPARATION - Pesanan sedang disiapkan untuk dikirim/dikirim, seperti makanan sedang dimasak atau barang sedang dikemas.
  • READY_FOR_PICKUP - Pesanan dapat diambil oleh penerima.
  • DELIVERED - Pesanan telah dikirim ke penerima
  • OUT_OF_STOCK - Satu atau beberapa item dalam pesanan habis.
  • CHANGE_REQUESTED - Pengguna meminta perubahan pada pesanan, dan perubahan tersebut sedang diproses.
  • RETURNED - Pesanan telah dikembalikan oleh pengguna setelah pengiriman.
  • REJECTED - Jika Anda tidak dapat memproses, menagih, atau "mengaktifkan" pesanan.
  • CANCELLED - Pesanan dibatalkan oleh pengguna.

Anda harus mengirimkan pembaruan pesanan untuk setiap status yang relevan dengan transaksi Anda. Misalnya, jika transaksi Anda memerlukan pemrosesan manual untuk mencatat pesanan setelah pesanan dilakukan, kirim pembaruan pesanan CREATED hingga pemrosesan tambahan selesai. Tidak semua pesanan memerlukan setiap nilai status.

Menguji project Anda

Saat menguji project, Anda dapat mengaktifkan mode sandbox di konsol Actions untuk menguji Action tanpa mengenakan biaya pada metode pembayaran. Untuk mengaktifkan mode sandbox, ikuti langkah-langkah berikut:

  1. Di Konsol Actions, klik Test di navigasi.
  2. Klik Setelan.
  3. Aktifkan opsi Sandbox Pengembangan.

Untuk transaksi fisik, Anda juga dapat menetapkan kolom isInSandbox ke true dalam contoh. Tindakan ini sama dengan mengaktifkan setelan mode sandbox di konsol Actions. Untuk melihat cuplikan kode yang menggunakan isInSandbox, lihat bagian Mengirim pembaruan pesanan.

Pemecahan masalah

Jika Anda mengalami masalah selama pengujian, sebaiknya baca langkah-langkah pemecahan masalah untuk transaksi.