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.

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

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.

Interface do seletor de opção de frete
Interface do seletor de opção de frete

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

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:

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