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

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

Eiji Kitamura

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

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

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

Например, в приведенной выше таблице в веб-кошельке Клиента А зарегистрированы две кредитные карты и один банковский счет. В этом случае приложение обрабатывает три платежных инструмента ( ****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);
      …

Продавец получит событие 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 : объект ошибки, специфичный для метода платежа. Вы можете попросить продавцов предоставить структурированную ошибку, но авторы спецификации веб-платежей рекомендуют сохранять ее в виде простой строки.

Пример кода

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

https://payhandler-demo.glitch.me

[обработчик платежей] работник службы

[обработчик платежей] интерфейс

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

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