İ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ıktan ve bir ödeme işlemi başlattıktan sonra, hizmet çalışanı satıcı ile ödeme uygulaması arasındaki iletişimin merkezi olarak hareket eder. Bu yayında, bir ödeme uygulamasının ödeme yöntemi, gönderim adresi veya iletişim bilgileri ile ilgili bilgileri hizmet çalışanı 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 müşterinin hangi ödeme yöntemini seçtiğini satıcıya bildirebilir. Bu özellik, satıcı örneğin belirli bir ödeme yöntemi markası için indirim kampanyası yayınlamak istediğinde kullanışlıdır.

Ö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 bilgileriyle PaymentRequestEvent.changePaymentMethod() öğesini çağırmalı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ı, Payment Request API'den bir paymentmethodchange etkinliği aldığında ödeme ayrıntılarını güncelleyip 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() 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ünü inceleyin.

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.

Bu özellik, adres toplama işlemi için ödeme uygulamalarına yetki verebildiği için satıcılar açısından yararlıdır. 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 belirlenen bir gönderim adresi olduğunda ödeme uygulaması, satıcıya çıkartılan adres bilgilerini bildirebilir. Bu durum satıcılara birden fazla avantaj sağlar:

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

Payment Handler API ile ödeme uygulaması, yeni kargo adresini bildirmek için hizmet çalışanından satıcıya bir "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.

[satıcı]

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 sonucu bir PaymentRequestDetailsUpdate nesnesi olur.

[ödeme işleyici] 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ı, 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 fiyat hakkında bilgilendirilmesi 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ı, bu bilgileri kullanarak toplam fiyatı güncellemeli ve ardından güncellenmiş PaymentDetailsUpdate ile yanıt vermelidir.

[satıcı]

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.
• Kargo seçeneği, belirtilen kargo adresi veya başka bir nedenden dolayı belirlenemiyor.

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 özel 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.