Обрабатывайте дополнительную платежную информацию с помощью сервисного работника

Как адаптировать ваше веб-приложение для платежей к системе веб-платежей и обеспечить лучший пользовательский опыт для клиентов.

Эйдзи Китамура

После того как веб-приложение для оплаты получает запрос на оплату и инициирует платежную транзакцию , сервис-воркер выступает в качестве центра связи между продавцом и платежным приложением. В этой статье объясняется, как платежное приложение может передавать продавцу информацию о способе оплаты, адресе доставки или контактных данных с помощью сервис-воркера.

Обработка необязательной платежной информации с помощью сервисного работника
Обработка необязательной платежной информации с помощью сервисного работника

Сообщите продавцу

Важно сообщить продавцу о следующих изменениях.

Изменение способа оплаты

Платежные приложения могут поддерживать несколько платежных инструментов с различными способами оплаты.

Клиент Способ оплаты Платежный инструмент
А Эмитент кредитной карты 1 ****1234
Эмитент кредитной карты 1 ****4242
Банк X ******123
Б Эмитент кредитной карты 2 ****5678
Банк X ******456

Например, в приведенной выше таблице в веб-кошельке клиента А зарегистрированы две кредитные карты и один банковский счет. В этом случае приложение обрабатывает три платежных инструмента ( ****1234 , ****4242 , ******123 ) и два способа оплаты (эмитент кредитной карты 1 и банк X). При совершении платежной транзакции платежное приложение может позволить клиенту выбрать один из платежных инструментов и использовать его для оплаты продавцу.

Пользовательский интерфейс выбора способа оплаты
Пользовательский интерфейс выбора способа оплаты

Платежное приложение может сообщить продавцу, какой способ оплаты выбрал покупатель, прежде чем отправить полный ответ об оплате. Это полезно, например, когда продавец хочет провести скидочную кампанию для определенной марки платежного метода.

С помощью веб-API обработчика платежей платежное приложение может отправить продавцу событие «изменение способа оплаты» через сервис-воркер, чтобы уведомить о новом идентификаторе способа оплаты. Сервис-воркер должен вызвать PaymentRequestEvent.changePaymentMethod() с информацией о новом способе оплаты.

Уведомите продавца об изменении способа оплаты.
Уведомите продавца об изменении способа оплаты.

Платежные приложения могут передавать объект methodDetails в качестве необязательного второго аргумента для PaymentRequestEvent.changePaymentMethod() . Этот объект может содержать произвольные данные о способе оплаты, необходимые продавцу для обработки события изменения.

[обработчик платежей] 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);
      …

Когда продавец получает событие paymentmethodchange от API запросов платежей, он может обновить данные платежа и отправить в ответ объект PaymentDetailsUpdate .

[торговец]

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

Когда продавец ответит, обещание, возвращенное методом PaymentRequestEvent.changePaymentMethod() будет выполнено с помощью объекта PaymentRequestDetailsUpdate .

[обработчик платежей] 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;
…

Используйте этот объект для обновления пользовательского интерфейса на стороне клиента. См. раздел «Отражение обновленных платежных данных» .

изменение адреса доставки

Платежные приложения могут передавать продавцу адрес доставки клиента в рамках платежной транзакции.

Это полезно для продавцов, поскольку они могут делегировать сбор адресов платежным приложениям. А поскольку адресные данные будут предоставляться в стандартном формате , продавец может рассчитывать на получение адресов доставки в единообразной структуре.

Кроме того, клиенты могут зарегистрировать свои адресные данные в предпочитаемом ими платежном приложении и использовать их для разных продавцов.

Пользовательский интерфейс для выбора адреса доставки
Пользовательский интерфейс для выбора адреса доставки

Платежные приложения могут предоставлять пользовательский интерфейс для редактирования адреса доставки или выбора предварительно зарегистрированной информации об адресе клиента при совершении платежа. Когда адрес доставки определяется временно, платежное приложение может уведомить продавца об удаленной информации об адресе. Это дает продавцам множество преимуществ:

  • Продавец может определить, соответствует ли покупатель региональным ограничениям на доставку товара (например, только внутри страны).
  • Продавец может изменить список вариантов доставки в зависимости от региона адреса доставки (например, международная стандартная или экспресс-доставка).
  • Продавец может рассчитать новую стоимость доставки в зависимости от адреса и обновить общую цену.

С помощью веб-API обработчика платежей платежное приложение может отправить продавцу событие «изменение адреса доставки» из сервис-воркера, чтобы уведомить о новом адресе доставки. Сервис-воркер должен вызвать PaymentRequestEvent.changeShippingAddress() с новым объектом адреса .

Сообщите продавцу об изменении адреса доставки.
Сообщите продавцу об изменении адреса доставки.

[обработчик платежей] 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);
      …

Ключевой термин: Засекреченный адрес . В этом случае сообщать продавцу полный адрес доставки не нужно, и это ставит под угрозу конфиденциальность клиентов. Продавец получает только те части адреса, которые необходимы для определения стоимости доставки. В частности, браузер очистит поля organization , phone , recipient , addressLine из предоставленного платежным приложением адреса перед тем, как вызвать событие shippingaddresschange в DOM продавца.

Продавец получит событие shippingaddresschange от API запроса платежа, чтобы ответить обновленными данными PaymentDetailsUpdate .

[торговец]

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

Когда продавец ответит, обещание, возвращенное PaymentRequestEvent.changeShippingAddress() будет выполнено с объектом PaymentRequestDetailsUpdate .

[обработчик платежей] 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;
…

Используйте этот объект для обновления пользовательского интерфейса на стороне клиента. См. раздел «Отражение обновленных платежных данных» .

Сообщите продавцу об изменении способа доставки.

Варианты доставки — это способы, которые продавцы используют для отправки приобретенных товаров покупателю. Типичные варианты доставки включают:

  • Бесплатная доставка
  • Экспресс-доставка
  • Международная доставка
  • Премиум международная доставка

Каждый из них имеет свою цену. Как правило, более быстрые методы и варианты обходятся дороже.

Продавцы, использующие API запроса платежа, могут делегировать этот выбор платежному приложению. Платежное приложение может использовать эту информацию для построения пользовательского интерфейса и предоставления клиенту возможности выбрать способ доставки.

Пользовательский интерфейс выбора вариантов доставки
Пользовательский интерфейс выбора вариантов доставки

Список вариантов доставки, указанных в API запроса платежа продавца, передается в сервис-воркер платежного приложения в качестве свойства объекта PaymentRequestEvent .

[торговец]

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

Платежное приложение может сообщить продавцу, какой способ доставки выбрал покупатель. Это важно как для продавца, так и для покупателя, поскольку изменение способа доставки также влияет на общую стоимость. Продавец должен быть проинформирован об актуальной цене для последующего подтверждения платежа, а покупатель также должен быть в курсе изменений.

С помощью API обработчика платежей платежное приложение может отправить продавцу событие "изменение способа доставки" из сервис-воркера. Сервис-воркер должен вызвать PaymentRequestEvent.changeShippingOption() с новым идентификатором способа доставки.

Сообщите продавцу об изменении способа доставки.
Сообщите продавцу об изменении способа доставки.

[обработчик платежей] 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);
      …

Продавец получит событие shippingoptionchange от API запроса платежа. Продавец должен использовать эту информацию для обновления общей цены, а затем отправить обновленный ответ с данными PaymentDetailsUpdate .

[торговец]

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

Когда продавец ответит, обещание, возвращенное методом PaymentRequestEvent.changeShippingOption() будет выполнено с помощью объекта PaymentRequestDetailsUpdate .

[обработчик платежей] 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;
…

Используйте этот объект для обновления пользовательского интерфейса на стороне клиента. См. раздел «Отражение обновленных платежных данных» .

Отобразить обновленные платежные реквизиты.

После того, как продавец завершит обновление платежных данных, промисы, возвращаемые методами .changePaymentMethod() , .changeShippingAddress() и .changeShippingOption() , разрешатся с общим объектом PaymentRequestDetailsUpdate . Обработчик платежей может использовать результат для отображения обновленной общей цены и вариантов доставки в пользовательском интерфейсе.

Продавцы могут возвращать ошибки по нескольким причинам:

  • Данный способ оплаты неприемлем.
  • Адрес доставки находится за пределами регионов, поддерживаемых ими.
  • В адресе доставки содержится неверная информация.
  • Способ доставки недоступен для указанного адреса доставки или по какой-либо другой причине.

Для отображения статуса ошибки используйте следующие свойства:

  • error : Удобочитаемая строка сообщения об ошибке. Это наилучший вариант для отображения клиентам.
  • shippingAddressErrors : Объект AddressErrors , содержащий подробную строку ошибки для каждого свойства адреса. Это полезно, если вы хотите открыть форму, позволяющую клиенту редактировать свой адрес, и вам нужно указать ему непосредственно на некорректные поля.
  • paymentMethodErrors : Объект ошибки, специфичный для способа оплаты. Вы можете попросить продавцов предоставить структурированную ошибку, но авторы спецификации Web Payments рекомендуют использовать простую строку.

Пример кода

Большинство примеров кода, представленных в этом документе, являются выдержками из тестового приложения.

Чтобы попробовать:

  1. Перейдите по ссылке https://paymentrequest-demo.glitch.me/ .
  2. Прокрутите страницу вниз.
  3. Нажмите кнопку «Добавить способ оплаты» .
  4. В поле « Идентификатор способа оплаты» введите https://paymenthandler-demo.glitch.me .
  5. Нажмите кнопку «Оплатить» рядом с полем.