Эта страница переведена с помощью Cloud Translation API.

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

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

Eiji Kitamura

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

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

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

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

Клиент	Способ оплаты	Платежный инструмент
А	Эмитент кредитной карты 1	`****1234`
	Эмитент кредитной карты 1	`****4242`
	Банк Х	`******123`
Б	Эмитент кредитной карты 2	`****5678`
Б	Банк Х	`******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 . Обработчик платежей может использовать результат, чтобы отобразить обновленную общую стоимость и варианты доставки в пользовательском интерфейсе.

Примечание. Объект PaymentRequestDetailsUpdate передается от продавца и содержит точную информацию, которую продавец ввел в объект PaymentDetailsUpdate через API запроса платежа. Лучший способ гарантировать, что продавцы предоставляют вам ожидаемую информацию, — это предоставить хорошую документацию для разработчиков или предоставить библиотеку JavaScript для управления информацией, или и то, и другое.

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

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

Используйте следующие свойства, чтобы отразить статус ошибки:

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

Образец кода

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

https://payhandler-demo.glitch.me

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

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

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

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