Esta página foi traduzida pela API Cloud Translation.

Como lidar com informações de pagamento opcionais com um service worker

Como adaptar seu app de pagamento baseado na Web para o Web Payments e oferecer uma melhor experiência do usuário aos clientes.

Eiji Kitamura

Quando um app de pagamento baseado na Web recebe uma solicitação e inicia um pagamento transação, o service worker vai agir como o hub de comunicação entre o comerciante e o app de pagamento. Esta postagem explica como um app de pagamento pode transmitir informações sobre a forma de pagamento, endereço de entrega ou informações de contato ao comerciante usando um service worker.

Como processar informações de pagamento opcionais com um service worker

Informar o comerciante sobre uma mudança na forma de pagamento

Os apps de pagamento aceitam vários instrumentos de pagamento com diferentes formas de pagamento.

Cliente	Forma de pagamento	Instrumento de pagamento
A	Emissor do cartão de crédito 1	`****1234`
	Emissor do cartão de crédito 1	`****4242`
	Banco X	`******123`
B	Emissor do cartão de crédito 2	`****5678`
B	Banco X	`******456`

Por exemplo, na tabela acima, a carteira do cliente A baseada na Web tem dois créditos e uma conta bancária registrada. Nesse caso, o app processa três instrumentos de pagamento (****1234, ****4242, ******123) e dois pagamentos (emissor do cartão de crédito 1 e Banco X). Em uma transação de pagamento, o valor aplicativo pode permitir que o cliente escolha um dos instrumentos de pagamento e o use para pagar para o comerciante.

interface do seletor de forma de pagamento

O app de pagamento pode informar ao comerciante qual forma de pagamento o cliente usa. selecionados antes de enviar a resposta de pagamento completa. Isso é útil quando o comerciante quer veicular uma campanha de descontos para uma marca de forma de pagamento específica, por exemplo.

Com a API Payment Handler, o app de pagamento pode enviar uma "alteração da forma de pagamento" evento ao comerciante por meio de um service worker para notificar a nova forma de pagamento identificador. O service worker deve invocar PaymentRequestEvent.changePaymentMethod() com a nova forma de pagamento informações imprecisas ou inadequadas.

Informar o comerciante sobre uma mudança na forma de pagamento

Apps de pagamento podem transmitir um objeto methodDetails como o segundo argumento opcional para PaymentRequestEvent.changePaymentMethod(). Esse objeto pode conter detalhes arbitrários da forma de pagamento necessários para o comerciante processar a mudança evento.

[gerenciador de pagamentos] 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);
      …

Quando o comerciante recebe um evento paymentmethodchange do recurso de pagamento Request, ele pode atualizar os detalhes de pagamento e responder com uma PaymentDetailsUpdate objeto.

[comerciante]

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

Quando o comerciante responde, prometer que PaymentRequestEvent.changePaymentMethod() retornados resolverão com uma PaymentRequestDetailsUpdate objeto.

[gerenciador de pagamentos] 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;
…

Use o objeto para atualizar a interface no front-end. Consulte Reflita sobre o detalhes de pagamento.

Informar o comerciante sobre uma mudança no endereço de entrega

Apps de pagamento podem fornecer o endereço de entrega de um cliente ao comerciante como parte de uma transação de pagamento.

Isso é útil para os comerciantes porque eles podem delegar a coleção de endereços a apps de pagamento. Além disso, como os dados de endereço serão fornecidos no formato padrão formato de dados, os o comerciante receberá endereços de entrega em uma estrutura consistente.

Além disso, os clientes podem registrar suas informações de endereço no e reutilizá-lo para comerciantes diferentes.

Interface do seletor de endereço de entrega

Os apps de pagamento podem fornecer uma interface para editar um endereço de entrega ou selecionar informações de endereço pré-registradas do cliente em uma transação de pagamento. Quando um endereço de entrega é determinado temporariamente, o aplicativo de pagamento pode permitir que o o comerciante tenha conhecimento das informações de endereço encobertas. Isso oferece aos comerciantes vários benefícios:

Um comerciante pode determinar se o cliente atende à restrição regional para enviar o item (por exemplo, somente para o país).
Um comerciante pode mudar a lista de opções de envio com base na região do endereço de entrega (por exemplo, regular internacional ou expresso).
O comerciante pode aplicar o novo custo de frete com base no endereço e atualizar os preço total.

Com a API Payment Handler, o app de pagamento pode enviar um "endereço de entrega" alterar" evento ao comerciante pelo service worker para notificar o novo envio endereço IP. O service worker deve invocar PaymentRequestEvent.changeShippingAddress() com o novo endereço objeto.

Informar o comerciante sobre uma mudança no endereço de entrega

[gerenciador de pagamentos] 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);
      …

Termo-chave : endereço encoberto. Nesse caso, não é necessário informar o endereço de entrega completo ao comerciante e isso coloca os clientes em risco privacidade. O comerciante recebe apenas as partes do endereço necessárias para determinar o custo de frete. Especificamente, o navegador vai limpar os campos organization, phone, recipient e addressLine do endereço informado pelo app de pagamento antes de gerar o evento shippingaddresschange no DOM do comerciante.

O comerciante recebe um evento shippingaddresschange na guia Solicite a API para que possam responder com o PaymentDetailsUpdate atualizado.

[comerciante]

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

Quando o comerciante responde, PaymentRequestEvent.changeShippingAddress() retornados resolverão com uma PaymentRequestDetailsUpdate objeto.

[gerenciador de pagamentos] 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;
…

Use o objeto para atualizar a interface no front-end. Consulte Reflita sobre o detalhes de pagamento.

Informar o comerciante sobre uma mudança na opção de frete

As opções de frete são os métodos de entrega que os comerciantes usam para enviar itens comprados a um cliente. As opções típicas de envio incluem:

Frete grátis
Frete expresso
Frete internacional
Frete internacional premium

Cada um tem um custo. Normalmente, métodos/opções mais rápidos são mais caros.

Os comerciantes que usam a API Payment Request podem delegar essa seleção a um pagamento app. O aplicativo de pagamento pode usar as informações para construir uma interface e permitir que o o cliente escolhe a opção de envio.

A lista de opções de envio especificadas na Payment Request API do comerciante é propagada para o service worker do app de pagamento como uma propriedade de PaymentRequestEvent:

[comerciante]

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

O app de pagamento pode informar ao comerciante qual opção de envio o cliente escolhidos. Isso é importante para o comerciante e para o cliente, porque alterar a opção de frete também altera o preço total. O comerciante precisa ser informado sobre o preço mais recente para a verificação de pagamento posteriormente e a o cliente também precisa estar ciente da mudança.

Com a API Payment Handler, o aplicativo de pagamento pode enviar uma "opção de envio alterar" para o comerciante a partir do service worker. O service worker precisa invocar PaymentRequestEvent.changeShippingOption() pelo novo ID da opção de frete.

Informar o comerciante sobre uma mudança na opção de frete

[gerenciador de pagamentos] 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);
      …

O comerciante recebe um evento shippingoptionchange na guia API Request. O comerciante precisa usar as informações para atualizar o preço total. e responder com a versão PaymentDetailsUpdate

[comerciante]

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

Quando o comerciante responde, prometer que PaymentRequestEvent.changeShippingOption() retornados resolverão com uma PaymentRequestDetailsUpdate objeto.

[gerenciador de pagamentos] 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;
…

Use o objeto para atualizar a interface no front-end. Consulte Reflita sobre o detalhes de pagamento.

Mostre os detalhes de pagamento atualizados.

Quando o comerciante terminar de atualizar os detalhes de pagamento, as promessas serão retornadas de .changePaymentMethod(), .changeShippingAddress() e .changeShippingOption() resolverá com uma PaymentRequestDetailsUpdate objeto. O gerenciador de pagamento pode usar o resultado para refletir o preço total atualizado. e opções de envio para a interface.

Observação : o objeto PaymentRequestDetailsUpdate é transmitido do comerciante e contém as informações exatas que ele colocou no objeto PaymentDetailsUpdate usando a API Payment Request. A melhor maneira de garantir que os comerciantes forneçam as informações esperadas é fornecer uma boa documentação para desenvolvedores, fornecer uma biblioteca JavaScript para controlar as informações ou ambos.

Os comerciantes podem retornar erros por alguns motivos:

A forma de pagamento não é aceita.
O endereço de entrega está fora das regiões aceitas.
O endereço de entrega contém informações inválidas.
A opção de envio não pode ser selecionada para o endereço de entrega fornecido ou por algum outro motivo.

Use as seguintes propriedades para refletir o status do erro:

error: string de erro legível por humanos. Esta é a melhor string para exibir para os clientes.
shippingAddressErrors AddressErrors Objeto que contém uma string de erro detalhada por propriedade de endereço. Isso é útil se você quiser abrir um formulário que permite ao cliente editar o endereço e você precisa apontá-los diretamente para os campos inválidos.
paymentMethodErrors: objeto de erro específico da forma de pagamento. Você pode pedir comerciantes forneçam um erro estruturado, mas os autores da especificação Web Payments recomendamos mantê-lo como uma string simples.

Código de amostra

A maioria dos exemplos de código que você viu neste documento foi trechos do seguinte App de exemplo funcional:

https://paymenthandler-demo.glitch.me

service worker [gerenciador de pagamentos]

Front-end [gerenciador de pagamentos]

Para testar:

Acesse https://paymentrequest-demo.glitch.me/ (link em inglês).
Acesse a parte inferior da página.
Pressione o botão Adicionar um pagamento.
Insira https://paymenthandler-demo.glitch.me no campo Identificador da forma de pagamento.
Pressione o botão Pagar ao lado do campo.