İsteğe bağlı ödeme bilgilerini hizmet ç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

Web tabanlı bir ödeme uygulaması bir ödeme isteği aldığında ve ödeme işlemi başlattığında hizmet çalışanı, satıcı ile ödeme uygulaması arasındaki iletişim merkezi olarak hareket eder. Bu yayında, bir ödeme uygulamasının ödeme yöntemi, gönderim adresi veya iletişim bilgileriyle ilgili bilgileri hizmet çalışanını kullanarak satıcıya nasıl iletebileceği açıklanmaktadır.

Satıcıyı ödeme yöntemi değişikliği hakkında bilgilendirme

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

Örneğin, yukarıdaki tabloda A müşterisinin web tabanlı cüzdanına iki kredi kartı ve bir banka hesabı kaydedilmiştir. Bu durumda uygulama üç ödeme aracı (****1234, ****4242, ******123) ve iki ödeme yöntemi (Kredi Kartı Çıkarıcı 1 ve X Bankası) kullanıyor. Ödeme uygulaması, ödeme işleminde müşterinin ödeme araçlarından birini seçmesine ve satıcı için ödeme yapmak üzere kullanmasına izin verebilir.

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

Ödeme işleyici API ile ödeme uygulaması, yeni ödeme yöntemi tanımlayıcısını bildirmek için bir servis ç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 bilgilerini kullanarak PaymentRequestEvent.changePaymentMethod() çağrısı yapmalıdır.

Ö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.

[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ı, PaymentRequest API'den paymentmethodchange etkinliği aldığında ödeme ayrıntılarını güncelleyebilir ve PaymentDetailsUpdate nesnesi ile 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() döndürülen söz, PaymentRequestDetailsUpdate nesnesi ile çözülür.

[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çtaki kullanıcı arayüzünü güncellemek için nesneyi kullanın. Güncellenen ödeme ayrıntılarını yansıtma bölümüne bakın.

Satıcıyı gönderim adresi değişikliği hakkında bilgilendirme

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

Satıcılar, adres toplama işlemini ödeme uygulamalarına delege edebildikleri için bu özellikten yararlanabilir. Ayrıca, adres verileri standart veri biçiminde sağlanacağından satıcı, gönderim adreslerini tutarlı bir yapıda alabilir.

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

Ödeme uygulamaları, bir gönderim adresini düzenlemek veya ödeme işleminde müşteri için önceden kaydedilmiş adres bilgilerini seçmek üzere kullanıcı arayüzü sağlayabilir. Geçici olarak bir gönderim adresi belirlendiğinde ödeme uygulaması, satıcıya çıkartılan adres bilgilerini bildirebilir. Bu durum satıcılara birden fazla 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ılar, gönderim adresinin bulunduğu bölgeye göre kargo seçenekleri listesini değiştirebilir (ör. uluslararası normal veya ekspres).
• Satıcılar, adrese göre yeni kargo maliyetini uygulayabilir ve toplam fiyatı güncelleyebilir.

Ödeme işleyici API ile ödeme uygulaması, yeni gönderim adresini bildirmek için hizmet çalışanından satıcıya "gönderim adresi değişikliği" etkinliği gönderebilir. Hizmet çalışanı, yeni adres nesnesi ile PaymentRequestEvent.changeShippingAddress() çağrısı yapmalı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 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      …

Satıcı, güncellenmiş PaymentDetailsUpdate ile yanıt verebilmek için PaymentRequest API'den bir shippingaddresschange etkinliği alır.

[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 PaymentRequestEvent.changeShippingAddress() sözünün çözülmesi sonucunda bir PaymentRequestDetailsUpdate nesnesi elde edilir.

[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çtaki kullanıcı arayüzünü güncellemek için nesneyi kullanın. Güncellenen ödeme ayrıntılarını yansıtma bölümüne bakın.

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

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

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

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

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

Satıcının Payment Request API'sinde belirtilen gönderim seçeneklerinin listesi, PaymentRequestEvent mülkü olarak ödeme uygulamasının hizmet işleyicisine dağıtılır.

[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 gönderim seçeneğini tercih ettiğini bildirebilir. Kargo seçeneği değiştirildiğinde toplam fiyat da değişeceğinden bu durum hem satıcı hem de müşteri için önemlidir. Satıcının, daha sonra ödeme doğrulaması için son fiyattan haberdar edilmesi ve müşterinin de değişiklikten haberdar olması gerekir.

Ödeme işleyici API ile ödeme uygulaması, servis çalışanından satıcıya "gönderim seçeneği değişikliği" etkinliği gönderebilir. Hizmet çalışanı, yeni gönderim seçeneği kimliğiyle PaymentRequestEvent.changeShippingOption() işlevini çağırmalı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 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      …

Satıcı, PaymentRequest 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() döndürülen söz, PaymentRequestDetailsUpdate nesnesi ile çözülür.

[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çtaki kullanıcı arayüzünü güncellemek için nesneyi kullanın. Güncellenen ödeme ayrıntılarını yansıtma bölümüne bakın.

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

Satıcı ödeme ayrıntılarını güncellemeyi tamamladıktan sonra .changePaymentMethod(), .changeShippingAddress() ve .changeShippingOption() tarafından döndürülen sözler ortak bir PaymentRequestDetailsUpdate nesnesi ile çözülür. Ödeme işleyici, sonucu kullanarak güncellenmiş toplam fiyatı ve gönderim seçeneklerini kullanıcı arayüzüne yansıtabilir.

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

• Ödeme yöntemi kabul edilmez.
• Gönderim adresi, desteklenen bölgelerin dışında.
• Gönderim adresi geçersiz bilgiler içeriyor.
• Gönderim seçeneği, belirtilen gönderim adresi veya başka bir nedenle seçilemiyor.

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

• error: Kullanıcı tarafından okunabilen hata dizesi. Bu, müşterilere gösterilecek en iyi dizedir.
• shippingAddressErrors: AddressErrors her adres mülkü için ayrıntılı hata dizesini içeren nesne. Müşterinin adresini düzenleyebileceği bir form açmak istiyorsanız ve müşteriyi doğrudan geçersiz alanlara yönlendirmeniz gerekiyorsa bu seçenek 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 spesifikasyonu yazarları, bunun basit bir dize olarak kalmasını önerir.

Örnek kod

Bu belgede gördüğünüz örnek kodların çoğu, aşağıdaki çalışan örnek uygulamadan alınmıştır:

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

Denemek için:

1. https://paymentrequest-demo.glitch.me/ adresine gidin.
2. Sayfanın alt kısmına gidin.
3. Ödeme düğmesi ekle'ye basın.
4. Ödeme Yöntemi Tanımlayıcısı alanına https://paymenthandler-demo.glitch.me yazın.
5. Alanın yanındaki Öde düğmesine basın.