İsteğe bağlı ödeme bilgilerini bir servis çalışanıyla işleme

Web tabanlı ödeme uygulamanızı Web Payments'a uyarlama ve müşterilere daha iyi bir kullanıcı deneyimi sunma.

Eiji Kitamura

Dikkat: Payment Request API'deki kargo ve adres desteği daha önce spesifikasyondan ve Chrome'dan kaldırılmıştı. Bu değişiklik spesifikasyonda geri alındı. Bu nedenle, kargo ve adresle ilgili dokümanları da geri aldık.

Web tabanlı bir ödeme uygulaması ödeme isteği alıp ödeme işlemini başlattıktan sonra hizmet çalışanı, satıcı ile ödeme uygulaması arasındaki iletişim merkezi olarak görev yapar. Bu yayında, bir ödeme uygulamasının hizmet çalışanı kullanarak ödeme yöntemi, kargo adresi veya iletişim bilgileriyle ilgili bilgileri satıcıya nasıl iletebileceği açıklanmaktadır.

İsteğe bağlı ödeme bilgilerini hizmet çalışanıyla işleme

Satıcıyı bilgilendirme

Satıcıyı aşağıdaki değişiklikler hakkında bilgilendirmeniz önemlidir.

Ödeme yöntemi değişikliği

Ödeme uygulamaları, farklı ödeme yöntemlerine sahip birden fazla ödeme aracını destekleyebilir.

Müşteri	Ödeme yöntemi	Ödeme Aracı
A	Kredi Kartı Veren Kuruluş 1	****1234
	Kredi Kartı Veren Kuruluş 1	****4242
	X Bankası	******123
B	Kredi Kartı Veren Kuruluş 2	****5678
	X Bankası	******456

Örneğin, yukarıdaki tabloda Müşteri A'nın web tabanlı cüzdanında iki kredi kartı ve bir banka hesabı kayıtlıdır. Bu durumda uygulama üç ödeme aracını (****1234, ****4242, ******123) ve iki ödeme yöntemini (Kredi Kartı Veren Kuruluş 1 ve Banka X) işler. Ödeme uygulamasında, ödeme işlemi sırasında müşterinin ödeme araçlarından birini seçip satıcıya ödeme yapmak için kullanmasına izin verilebilir.

Ödeme yöntemi seçici kullanıcı arayüzü

Ödeme uygulaması, tam ödeme yanıtını göndermeden önce satıcıya müşterinin hangi ödeme yöntemini seçtiğini bildirebilir. Bu, satıcının belirli bir ödeme yöntemi markası için indirim kampanyası yayınlamak istediği durumlarda kullanışlıdır.

Web Tabanlı Payment Handler API ile ödeme uygulaması, yeni ödeme yöntemi tanımlayıcısını bildirmek için bir hizmet çalışanı aracılığıyla satıcıya "ödeme yöntemi değişikliği" etkinliği gönderebilir. Hizmet çalışanı, yeni ödeme yöntemi bilgileriyle PaymentRequestEvent.changePaymentMethod() yöntemini çağırmalıdır.

Satıcıya ödeme yöntemi değişikliğini bildirme

Ödeme uygulamaları, PaymentRequestEvent.changePaymentMethod() için isteğe bağlı ikinci bağımsız değişken olarak bir methodDetails nesnesi iletebilir. Bu nesne, satıcının değişiklik etkinliğini işlemesi için gereken rastgele ödeme yöntemi ayrıntılarını içerebilir.

Uyarı: İşlem tamamlanmadan önce müşteriyle ilgili ayrıntılı bilgilerin satıcıyla paylaşılması gizlilik riski oluşturabilir. En iyi uygulama olarak, ödeme uygulamaları gereksiz ayrıntıları mümkün olduğunca atlamalıdır.

[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);
      …

Satıcı, Payment Request API'den bir paymentmethodchange etkinliği aldığında ödeme ayrıntılarını güncelleyebilir ve bir PaymentDetailsUpdate nesnesiyle yanıt verebilir.

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

Satıcı yanıt verdiğinde PaymentRequestEvent.changePaymentMethod() tarafından döndürülen promise, bir PaymentRequestDetailsUpdate nesnesiyle çözümlenir.

[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;
…

Ön uçta kullanıcı arayüzünü güncellemek için nesneyi kullanın. Güncellenen ödeme ayrıntılarını yansıtma bölümünü inceleyin.

Kargo adresi değişikliği

Ödeme uygulamaları, ödeme işleminin bir parçası olarak müşterinin kargo adresini satıcıya sağlayabilir.

Bu, satıcılar için yararlıdır çünkü adres toplama işlemini ödeme uygulamalarına devredebilirler. Ayrıca, adres verileri standart veri biçiminde sağlanacağından satıcı, kargo adreslerini tutarlı bir yapıda almayı bekleyebilir.

Ayrıca müşteriler, adres bilgilerini tercih ettikleri ödeme uygulamasına kaydedebilir ve farklı satıcılar için tekrar kullanabilir.

Kargo adresi seçici kullanıcı arayüzü

Ödeme uygulamaları, ödeme işleminde müşterinin kargo adresini düzenlemesi veya önceden kayıtlı adres bilgilerini seçmesi için bir kullanıcı arayüzü sağlayabilir. Kargo adresi geçici olarak belirlendiğinde ödeme uygulaması, satıcıya sansürlenmiş adres bilgilerini bildirebilir. Bu, satıcılara birçok avantaj sağlar:

• Satıcı, müşterinin ürünü göndermek için bölgesel kısıtlamayı karşılayıp karşılamadığını belirleyebilir (ör. yalnızca yurt içi).
• Satıcı, kargo adresinin bölgesine göre kargo seçenekleri listesini değiştirebilir (ör. uluslararası normal veya ekspres).
• Satıcı, adrese göre yeni kargo maliyetini uygulayabilir ve toplam fiyatı güncelleyebilir.

Web Tabanlı Payment Handler API ile ödeme uygulaması, yeni kargo adresini bildirmek için hizmet çalışanından satıcıya bir "kargo adresi değişikliği" etkinliği gönderebilir. Hizmet çalışanı, yeni adres nesnesiyle PaymentRequestEvent.changeShippingAddress() yöntemini çağırmalıdır.

Satıcıya kargo adresi değişikliğini bildirme

[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);
      …

Anahtar terim: Redacted address (Çıkartılan adres). Bu durumda satıcıya tam kargo adresinin bildirilmesi gerekli değildir ve müşterilerin gizliliğini riske atar. Satıcı, adresin yalnızca kargo maliyetini belirlemek için ihtiyaç duyduğu kısımlarını alır. Özellikle tarayıcı, satıcının DOM'unda shippingaddresschange etkinliğini tetiklemeden önce ödeme uygulaması tarafından sağlanan adresteki organization, phone, recipient, addressLine alanlarını temizler.

Satıcı, Payment Request API'den bir shippingaddresschange etkinliği alır. Böylece güncellenmiş PaymentDetailsUpdate ile yanıt verebilir.

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

Satıcı yanıt verdiğinde döndürülen promise PaymentRequestEvent.changeShippingAddress() , bir PaymentRequestDetailsUpdate nesnesiyle çözümlenir.

[payment handler] 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;
…

Ön uçta kullanıcı arayüzünü güncellemek için nesneyi kullanın. Güncellenen ödeme ayrıntılarını yansıtma bölümünü inceleyin.

Satıcıya kargo seçeneği değişikliğini bildirme

Kargo seçenekleri, satıcıların satın alınan ürünleri müşteriye göndermek için kullandığı teslimat yöntemleridir. Tipik kargo seçenekleri şunlardır:

• Ücretsiz gönderim
• Ekspres kargo
• Uluslararası nakliye
• Premium uluslararası kargo

Her birinin kendine ait bir maliyeti vardır. Genellikle daha hızlı yöntemler ve seçenekler daha pahalıdır.

Payment Request API'yi kullanan satıcılar, bu seçimi bir ödeme uygulamasına devredebilir. Ödeme uygulaması, kullanıcı arayüzü oluşturmak ve müşterinin kargo seçeneği belirlemesine olanak tanımak için bu bilgileri kullanabilir.

Kargo seçeneği belirleme kullanıcı arayüzü

Satıcının Payment Request API'sinde belirtilen kargo seçeneklerinin listesi, ödeme uygulamasının hizmet çalışanına PaymentRequestEvent özelliğinin bir özelliği olarak iletilir.

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

Ödeme uygulaması, satıcıya müşterinin hangi kargo seçeneğini tercih ettiğini bildirebilir. Gönderim seçeneğinin değiştirilmesi toplam fiyatı da değiştirdiğinden bu durum hem satıcı hem de müşteri için önemlidir. Satıcının, ödeme doğrulama için en güncel fiyattan haberdar olması ve müşterinin de bu değişiklikten haberdar olması gerekir.

Payment Handler API ile ödeme uygulaması, hizmet çalışanından satıcıya "gönderim seçeneği değişikliği" etkinliği gönderebilir. Hizmet çalışanı, yeni kargo seçeneği kimliğiyle PaymentRequestEvent.changeShippingOption() yöntemini çağırmalıdır.

Satıcıyı kargo seçeneği değişikliği hakkında bilgilendirme

[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);
      …

Satıcı, Payment Request API'den bir shippingoptionchange etkinliği alır. Satıcı, toplam fiyatı güncellemek için bu bilgileri kullanmalı ve ardından güncellenmiş PaymentDetailsUpdate ile yanıt vermelidir.

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

Satıcı yanıt verdiğinde PaymentRequestEvent.changeShippingOption() tarafından döndürülen promise, bir PaymentRequestDetailsUpdate nesnesiyle çözümlenir.

[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;
…

Ön uçta kullanıcı arayüzünü güncellemek için nesneyi kullanın. Güncellenen ödeme ayrıntılarını yansıtma bölümünü inceleyin.

Güncellenen ödeme ayrıntılarını yansıtma

Satıcı, ödeme ayrıntılarını güncellemeyi tamamladığında .changePaymentMethod(), .changeShippingAddress() ve .changeShippingOption() tarafından döndürülen vaatler ortak bir PaymentRequestDetailsUpdate nesnesiyle çözümlenir. Ödeme işleyici, güncellenen toplam fiyatı ve kargo seçeneklerini kullanıcı arayüzüne yansıtmak için sonucu kullanabilir.

Not: PaymentRequestDetailsUpdate nesnesi satıcıdan iletilir ve satıcının Payment Request API ile PaymentDetailsUpdate nesnesine eklediği bilgilerin aynısını içerir. Satıcıların beklediğiniz bilgileri size vermesini sağlamak için iyi bir geliştirici belgeleri veya bilgileri kontrol etmek için bir JavaScript kitaplığı ya da her ikisini birden sağlayın.

Satıcılar birkaç nedenden dolayı hata döndürebilir:

• Ödeme yöntemi kabul edilmiyor.
• Kargo adresi, desteklenen bölgelerin dışındaysa
• Kargo adresi geçersiz bilgiler içeriyor.
• Gönderim seçeneği, belirtilen kargo adresi için seçilemiyor veya başka bir sorun var.

Hata durumunu yansıtmak için aşağıdaki özellikleri kullanın:

• error: Okunabilir hata dizesi. Müşterilere gösterilecek en iyi dize budur.
• shippingAddressErrors: Adres özelliği başına ayrıntılı hata dizesi içeren AddressErrors nesnesi. Bu, müşterinin adresini düzenlemesine olanak tanıyan bir form açmak ve müşteriyi doğrudan geçersiz alanlara yönlendirmek istediğinizde kullanışlıdır.
• paymentMethodErrors: Ödeme yöntemine özgü hata nesnesi. Satıcılardan yapılandırılmış bir hata sağlamalarını isteyebilirsiniz ancak Web Payments spesifikasyon yazarları, hatanın basit bir dize olarak tutulmasını önerir.