Menangani informasi pembayaran opsional dengan pekerja layanan

Cara menyesuaikan aplikasi pembayaran berbasis web Anda dengan Pembayaran Web dan memberikan pengalaman pengguna yang lebih baik bagi pelanggan.

Eiji Kitamura

Peringatan: Dukungan pengiriman dan alamat di Payment Request API pernah dihapus dari spesifikasi dan dari Chrome, tetapi diubah kembali dalam spesifikasi. Oleh karena itu, kami juga telah mengembalikan dokumentasi tentang pengiriman dan alamat.

Setelah aplikasi pembayaran berbasis web menerima permintaan pembayaran dan memulai transaksi pembayaran, pekerja layanan akan bertindak sebagai pusat komunikasi antara penjual dan aplikasi pembayaran. Postingan ini menjelaskan cara aplikasi pembayaran dapat meneruskan informasi tentang metode pembayaran, alamat pengiriman, atau informasi kontak kepada penjual menggunakan pekerja layanan.

Menangani informasi pembayaran opsional dengan pekerja layanan

Memberi tahu penjual tentang perubahan metode pembayaran

Aplikasi pembayaran dapat mendukung beberapa instrumen pembayaran dengan metode pembayaran yang berbeda.

Pelanggan	Metode Pembayaran	Instrumen Pembayaran
A	Penerbit Kartu Kredit 1	****1234
	Penerbit Kartu Kredit 1	****4242
	Bank X	******123
B	Penerbit Kartu Kredit 2	****5678
	Bank X	******456

Misalnya, dalam tabel di atas, dompet berbasis web Pelanggan A memiliki dua kartu kredit dan satu rekening bank yang terdaftar. Dalam hal ini, aplikasi menangani tiga instrumen pembayaran (****1234, ****4242, ******123) dan dua metode pembayaran (Penerbit Kartu Kredit 1 dan Bank X). Pada transaksi pembayaran, aplikasi pembayaran dapat memungkinkan pelanggan memilih salah satu instrumen pembayaran dan menggunakannya untuk membayar penjual.

UI pemilih metode pembayaran

Aplikasi pembayaran dapat memberi tahu penjual metode pembayaran yang dipilih pelanggan sebelum mengirim respons pembayaran lengkap. Hal ini berguna saat penjual ingin menjalankan kampanye diskon untuk merek metode pembayaran tertentu, misalnya.

Dengan Payment Handler API, aplikasi pembayaran dapat mengirim peristiwa "perubahan metode pembayaran" kepada penjual melalui pekerja layanan untuk memberi tahu ID metode pembayaran yang baru. Pekerja layanan harus memanggil PaymentRequestEvent.changePaymentMethod() dengan informasi metode pembayaran baru.

Memberi tahu penjual tentang perubahan metode pembayaran

Aplikasi pembayaran dapat meneruskan objek methodDetails sebagai argumen kedua opsional untuk PaymentRequestEvent.changePaymentMethod(). Objek ini dapat berisi detail metode pembayaran arbitrer yang diperlukan bagi penjual untuk memproses peristiwa perubahan.

Peringatan: Membagikan informasi mendetail tentang pelanggan kepada penjual sebelum transaksi diselesaikan berpotensi menimbulkan risiko privasi. Sebagai praktik terbaik, aplikasi pembayaran harus menghilangkan detail yang tidak diperlukan sebanyak mungkin.

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_METHOD_CHANGED':
        const newMethod = e.data.paymentMethod;
        const newDetails = e.data.methodDetails;
        // Redact or check that no sensitive information is passed in
        // `newDetails`.
        // Notify the merchant of the payment method change
        details =
          await payment_request_event.changePaymentMethod(newMethod, newDetails);
      …

Saat penjual menerima peristiwa paymentmethodchange dari Payment Request API, mereka dapat memperbarui detail pembayaran dan merespons dengan objek PaymentDetailsUpdate.

[merchant]

request.addEventListener('paymentmethodchange', e => {
  if (e.methodName === 'another-pay') {
    // Apply $10 discount for example.
    const discount = {
      label: 'special discount',
      amount: {
        currency: 'USD',
        // The value being string complies the spec
        value: '-10.00'
      }
    };
    let total = 0;
    details.displayItems.push(discount);
    for (let item of details.displayItems) {
     total += parseFloat(item.amount.value);
    }
    // Convert the number back to string
    details.total.amount.value = total.toString();
  }
  // Pass a promise to `updateWith()` and send updated payment details
  e.updateWith(details);
});

Saat penjual merespons, promise yang PaymentRequestEvent.changePaymentMethod() ditampilkan akan di-resolve dengan objek PaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the payment method change
        details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Gunakan objek untuk memperbarui UI di frontend. Lihat Mencerminkan detail pembayaran yang diperbarui.

Memberi tahu penjual tentang perubahan alamat pengiriman

Aplikasi pembayaran dapat memberikan alamat pengiriman pelanggan kepada penjual sebagai bagian dari transaksi pembayaran.

Hal ini berguna bagi penjual karena mereka dapat mendelegasikan pengumpulan alamat ke aplikasi pembayaran. Selain itu, karena data alamat akan diberikan dalam format data standar, penjual dapat menerima alamat pengiriman dalam struktur yang konsisten.

Selain itu, pelanggan dapat mendaftarkan informasi alamat mereka dengan aplikasi pembayaran pilihan mereka dan menggunakannya kembali untuk penjual yang berbeda.

UI pemilih alamat pengiriman

Aplikasi pembayaran dapat menyediakan UI untuk mengedit alamat pengiriman atau memilih informasi alamat yang terdaftar sebelumnya untuk pelanggan pada transaksi pembayaran. Saat alamat pengiriman ditentukan untuk sementara, aplikasi pembayaran dapat memberi tahu penjual tentang informasi alamat yang disamarkan. Dengan begitu, penjual akan mendapatkan beberapa manfaat:

• Merchant dapat menentukan apakah pelanggan memenuhi batasan regional untuk mengirim item (misalnya, hanya domestik).
• Penjual dapat mengubah daftar opsi pengiriman berdasarkan wilayah alamat pengiriman (Misalnya, reguler atau ekspres internasional).
• Penjual dapat menerapkan biaya pengiriman baru berdasarkan alamat dan memperbarui harga total.

Dengan Payment Handler API, aplikasi pembayaran dapat mengirim peristiwa "perubahan alamat pengiriman" kepada penjual dari pekerja layanan untuk memberi tahu alamat pengiriman yang baru. Pekerja layanan harus memanggil PaymentRequestEvent.changeShippingAddress() dengan objek alamat baru.

Memberi tahu penjual tentang perubahan alamat pengiriman

[payment handler] service-worker.js

...
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      …

Istilah penting: Alamat disamarkan. Dalam hal ini, Anda tidak perlu memberi tahu alamat pengiriman lengkap kepada penjual dan hal ini berisiko terhadap privasi pelanggan. Penjual hanya menerima bagian alamat yang diperlukan untuk menentukan biaya pengiriman. Secara khusus, browser akan menghapus kolom organization, phone, recipient, addressLine dari alamat yang diberikan aplikasi pembayaran sebelum menaikkan peristiwa shippingaddresschange di DOM penjual.

Penjual akan menerima peristiwa shippingaddresschange dari Payment Request API sehingga mereka dapat merespons dengan PaymentDetailsUpdate yang diperbarui.

[merchant]

request.addEventListener('shippingaddresschange', e => {
  // Read the updated shipping address and update the request.
  const addr = request.shippingAddress;
  const details = getPaymentDetailsFromShippingAddress(addr);
  // `updateWith()` sends back updated payment details
  e.updateWith(details);
});

Saat penjual merespons, promise PaymentRequestEvent.changeShippingAddress() yang ditampilkan akan diselesaikan dengan objek PaymentRequestDetailsUpdate.

[pengendali pembayaran] service-worker.js

…
        // Notify the merchant of the shipping address change
        details = await payment_request_event.changeShippingAddress(newAddress);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Gunakan objek untuk memperbarui UI di frontend. Lihat Mencerminkan detail pembayaran yang diperbarui.

Beri tahu penjual tentang perubahan opsi pengiriman

Opsi pengiriman adalah metode pengiriman yang digunakan penjual untuk mengirimkan item yang dibeli kepada pelanggan. Opsi pengiriman yang umum meliputi:

• Gratis ongkos kirim
• Pengiriman ekspres
• Pengiriman internasional
• Pengiriman internasional premium

Setiap opsi memiliki biayanya sendiri. Biasanya metode/opsi yang lebih cepat lebih mahal.

Penjual yang menggunakan Payment Request API dapat mendelegasikan pilihan ini ke aplikasi pembayaran. Aplikasi pembayaran dapat menggunakan informasi tersebut untuk membuat UI dan memungkinkan pelanggan memilih opsi pengiriman.

UI pemilih opsi pengiriman

Daftar opsi pengiriman yang ditentukan di Payment Request API penjual di-propagasi ke pekerja layanan aplikasi pembayaran sebagai properti PaymentRequestEvent.

[merchant]

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: { transactionId: '****' }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  shippingOptions: [{
    id: 'standard',
    label: 'Standard',
    amount: { value: '0.00', currency: 'USD' },
    selected: true
  }, {
    id: 'express',
    label: 'Express',
    amount: { value: '5.00', currency: 'USD' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {  requestShipping: true });

Aplikasi pembayaran dapat memberi tahu penjual opsi pengiriman yang dipilih pelanggan. Hal ini penting bagi penjual dan pelanggan karena mengubah opsi pengiriman juga akan mengubah harga total. Penjual perlu diberi tahu harga terbaru untuk verifikasi pembayaran nanti dan pelanggan juga perlu mengetahui perubahan tersebut.

Dengan Payment Handler API, aplikasi pembayaran dapat mengirim peristiwa "perubahan opsi pengiriman" kepada penjual dari pekerja layanan. Pekerja layanan harus memanggil PaymentRequestEvent.changeShippingOption() dengan ID opsi pengiriman baru.

Beri tahu penjual tentang perubahan opsi pengiriman

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      …

Penjual akan menerima peristiwa shippingoptionchange dari Payment Request API. Penjual harus menggunakan informasi tersebut untuk memperbarui harga total, lalu merespons dengan PaymentDetailsUpdate yang diperbarui.

[merchant]

request.addEventListener('shippingoptionchange', e => {
  // selected shipping option
  const shippingOption = request.shippingOption;
  const newTotal = {
    currency: 'USD',
    label: 'Total due',
    value: calculateNewTotal(shippingOption),
  };
  // `updateWith()` sends back updated payment details
  e.updateWith({ total: newTotal });
});

Saat penjual merespons, promise yang ditampilkan PaymentRequestEvent.changeShippingOption() akan di-resolve dengan objek PaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping option change
        details = await payment_request_event.changeShippingOption(newOption);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Gunakan objek untuk memperbarui UI di frontend. Lihat Menampilkan detail pembayaran yang diperbarui.

Mencerminkan detail pembayaran yang diperbarui

Setelah penjual selesai memperbarui detail pembayaran, promise yang ditampilkan dari .changePaymentMethod(), .changeShippingAddress(), dan .changeShippingOption() akan di-resolve dengan objek PaymentRequestDetailsUpdate umum. Pengendali pembayaran dapat menggunakan hasilnya untuk mencerminkan opsi harga total dan pengiriman yang diperbarui ke UI.

Catatan: Objek PaymentRequestDetailsUpdate diteruskan dari penjual dan berisi informasi persis yang dimasukkan penjual ke dalam objek PaymentDetailsUpdate melalui Payment Request API. Cara terbaik untuk memastikan bahwa penjual memberikan informasi yang Anda harapkan adalah memberikan dokumentasi developer yang baik, atau menyediakan library JavaScript untuk mengontrol informasi, atau keduanya.

Penjual mungkin menampilkan error karena beberapa alasan:

• Metode pembayaran tidak dapat diterima.
• Alamat pengiriman berada di luar wilayah yang didukung.
• Alamat pengiriman berisi informasi yang tidak valid.
• Opsi pengiriman tidak dapat dipilih untuk alamat pengiriman yang diberikan atau alasan lainnya.

Gunakan properti berikut untuk mencerminkan status error:

• error: String error yang dapat dibaca manusia. Ini adalah {i>string<i} terbaik untuk ditampilkan kepada pelanggan.
• shippingAddressErrors: objek AddressErrors yang berisi string error mendetail per properti alamat. Hal ini berguna jika Anda ingin membuka formulir yang memungkinkan pelanggan mengedit alamat mereka dan Anda perlu mengarahkan mereka langsung ke kolom yang tidak valid.
• paymentMethodErrors: Objek error khusus metode pembayaran. Anda dapat meminta penjual untuk memberikan error terstruktur, tetapi penulis spesifikasi Pembayaran Web menyarankan untuk tetap menggunakan string sederhana.

Kode contoh

Sebagian besar contoh kode yang Anda lihat dalam dokumen ini adalah kutipan dari aplikasi contoh yang berfungsi berikut:

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

Untuk mencobanya:

1. Buka https://paymentrequest-demo.glitch.me/.
2. Arahkan kursor ke bagian bawah laman.
3. Tekan Tambahkan tombol pembayaran.
4. Masukkan https://paymenthandler-demo.glitch.me ke kolom ID Metode Pembayaran.
5. Tekan tombol Pay di samping kolom.