O ciclo de uma transação de pagamento

Saiba como os comerciantes integram apps de pagamento e como as transações de pagamento funcionam com a API Payment Request.

Eiji Kitamura

Milica Mihajlija

As APIs Web Payments são recursos de pagamento dedicados criados no navegador pela primeira vez. Com o Web Payments, a integração do comerciante com apps de pagamento fica mais simples e a experiência do cliente fica mais simples e segura.

Para saber mais sobre os benefícios de usar o Web Payments, consulte Como capacitar apps de pagamento com o Web Payments.

Neste artigo, explicamos como fazer uma transação de pagamento no site de um comerciante e entendemos como funciona a integração do app de pagamento.

O processo envolve seis etapas:

1. O comerciante inicia uma transação de pagamento.
2. O comerciante mostra um botão de pagamento.

3. O cliente pressiona o botão de pagamento.

   

4. O navegador abre o app de pagamento.

   

5. Se o cliente alterar detalhes (como opções de envio ou o endereço), o comerciante atualizará os detalhes da transação.

   

6. Depois que o cliente confirma a compra, o comerciante valida o pagamento e conclui a transação.

   

Etapa 1: o comerciante inicia uma transação de pagamento

Quando um cliente decide fazer uma compra, o comerciante inicia a transação de pagamento construindo um objeto PaymentRequest. Esse objeto inclui informações importantes sobre a transação:

• Formas de pagamento aceitáveis e os dados delas para processar a transação
• Detalhes, como preço total (obrigatório) e informações sobre os itens.
• Opções em que os comerciantes podem solicitar informações de frete, como um endereço e uma opção de envio.
• Os comerciantes também podem solicitar o endereço de faturamento, o nome do pagador, e-mail e número de telefone.
• Os comerciantes também podem incluir o tipo de frete opcional (shipping, delivery ou pickup) no PaymentRequest. O app de pagamento pode usar isso como uma dica para mostrar os rótulos corretos na interface.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Com as informações da transação, o navegador passa por um processo de descoberta de apps de pagamento especificados no PaymentRequest com base nos identificadores da forma de pagamento. Dessa forma, o navegador pode determinar que o app de pagamento será iniciado assim que o comerciante estiver pronto para prosseguir com a transação.

Para saber como o processo de descoberta funciona, consulte Como configurar uma forma de pagamento.

Etapa 2: o comerciante mostra um botão de pagamento

Os comerciantes aceitam muitas formas de pagamento, mas só devem apresentar os botões de pagamento daqueles que um cliente realmente pode usar. Mostrar um botão de pagamento inutilizável é uma experiência do usuário ruim. Se um comerciante conseguir prever que uma forma de pagamento especificada no objeto PaymentRequest não vai funcionar para o cliente, ele poderá fornecer uma solução substituta ou não mostrar esse botão.

Usando uma instância de PaymentRequest, o comerciante pode consultar se um cliente tem o app de pagamento disponível.

O cliente tem o app de pagamento disponível?

O método canMakePayment() de PaymentRequest retornará true se um app de pagamento estiver disponível no dispositivo do cliente. "Disponível" significa que um app de pagamento compatível com a forma de pagamento foi descoberto e que o app de pagamento específico da plataforma foi instalado ou que o app de pagamento baseado na Web está pronto para ser registrado.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Etapa 3: o cliente pressiona o botão de pagamento

Quando o cliente pressiona o botão de pagamento, o comerciante chama o método show() da instância PaymentRequest, que aciona imediatamente a inicialização da interface de pagamento.

Caso o preço total final seja definido dinamicamente (por exemplo, extraído de um servidor), o comerciante poderá adiar o lançamento da interface de pagamento até que o valor total seja conhecido.

Adiar o lançamento da interface de pagamento

Confira uma demonstração de como adiar a interface de pagamento até que o preço total final seja determinado.

Para adiar a interface de pagamento, o comerciante transmite uma promessa ao método show(). O navegador mostrará um indicador de carregamento até que a promessa seja resolvida e a transação esteja pronta para começar.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

Se não houver uma promessa especificada como argumento para show(), o navegador iniciará a interface de pagamento imediatamente.

Etapa 4: o navegador abre o app de pagamento

O navegador pode iniciar um app de pagamento específico da plataforma ou baseado na Web. Saiba mais sobre como o Chrome determina qual app de pagamento será iniciado.

A forma como o app de pagamento é criado depende do desenvolvedor em grande parte, mas os eventos emitidos de e para o comerciante, bem como a estrutura dos dados transmitidos com esses eventos, são padronizados.

Quando o app de pagamento é iniciado, ele recebe as informações da transação transmitidas ao objeto PaymentRequest na Etapa 1, que incluem o seguinte:

• Dados da forma de pagamento
• Preço total
• Opções de pagamento

O app de pagamento usa as informações da transação para rotular a interface.

Etapa 5: como um comerciante pode atualizar os detalhes da transação dependendo das ações do cliente

Os clientes têm a opção de alterar os detalhes da transação, como forma de pagamento e opção de envio, no app de pagamento. Enquanto o cliente faz as alterações, o comerciante recebe os eventos de alteração e atualiza os detalhes da transação.

Existem quatro tipos de eventos que um comerciante pode receber:

• Evento de alteração da forma de pagamento
• Evento de alteração do endereço de entrega
• Evento de alteração da opção de frete
• Evento de validação do comerciante

Evento de alteração da forma de pagamento

Um app de pagamento pode aceitar várias formas de pagamento e um comerciante pode oferecer um desconto especial, dependendo da seleção do cliente. Para atender a esse caso de uso, o evento de alteração da forma de pagamento pode informar o comerciante sobre a nova forma de pagamento para que ele possa atualizar o preço total com o desconto e retorná-lo ao app de pagamento.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Evento de alteração do endereço de entrega

Um app de pagamento tem a opção de informar o endereço de entrega do cliente. Isso é conveniente para os clientes porque eles não precisam inserir manualmente qualquer detalhe em um formulário e podem armazenar o endereço de entrega nos apps de pagamento de sua preferência, em vez de em vários sites diferentes de comerciantes.

Se um cliente atualizar o endereço de entrega em um app de pagamento após o início da transação, um evento 'shippingaddresschange' será enviado ao comerciante. Esse evento ajuda o comerciante a determinar o custo do frete com base no novo endereço, atualizar o preço total e devolvê-lo ao app de pagamento.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

Se o comerciante não conseguir fazer envios para o endereço atualizado, ele poderá enviar uma mensagem de erro adicionando um parâmetro de erro aos detalhes da transação retornados ao app de pagamento.

Evento de alteração da opção de frete

Um comerciante pode oferecer várias opções de frete ao cliente e delegar essa escolha ao app de pagamento. As opções de frete são exibidas como uma lista de preços e nomes de serviços em que o cliente pode selecionar. Exemplo:

• Frete padrão – sem custo financeiro
• Frete expresso – R$ 5

Quando um cliente atualiza a opção de frete em um app de pagamento, um evento 'shippingoptionchange' é enviado ao comerciante. O comerciante pode determinar o custo do frete, atualizar o preço total e devolvê-lo ao app de pagamento.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

O comerciante também pode modificar dinamicamente as opções de envio com base no endereço de entrega do cliente. Isso é útil quando um comerciante quer oferecer diferentes conjuntos de opções de frete para clientes nacionais e internacionais.

Evento de validação do comerciante

Por motivos de segurança, um app de pagamento pode realizar uma validação do comerciante antes de avançar para o fluxo de pagamento. O design do mecanismo de validação depende do app de pagamento, mas o evento de validação do comerciante serve para informá-lo sobre o URL que pode ser usado para se validar.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Etapa 6: o comerciante valida o pagamento e conclui a transação

Quando o cliente autoriza o pagamento, o método show() retorna uma promessa que é resolvida em um PaymentResponse. O objeto PaymentResponse inclui as seguintes informações:

• Detalhes do resultado do pagamento
• Endereço de entrega
• Opção de frete
• Dados de contato

Nesse momento, a interface do navegador ainda pode mostrar um indicador de carregamento, o que significa que a transação ainda não foi concluída.

Se o app de pagamento for encerrado devido a uma falha ou erro de pagamento, a promessa retornada de show() será rejeitada, e o navegador encerrará a transação de pagamento.

Processamento e validação do pagamento

O details em PaymentResponse é o objeto da credencial de pagamento retornado do app de pagamento. O comerciante pode usar a credencial para processar ou validar o pagamento. O modo como esse processo essencial funciona depende do gerenciador de pagamentos.

Concluir ou repetir a transação

Depois que o comerciante determina se a transação foi bem-sucedida ou falhou, ele pode:

• Chame o método .complete() para concluir a transação e dispense o indicador de carregamento.
• Permita que o cliente tente chamar o método retry() novamente.

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Próximas etapas

• Saiba como declarar um identificador de forma de pagamento em detalhes em Como configurar uma forma de pagamento.
• Saiba como criar um app de pagamento específico da plataforma no Guia do desenvolvedor de apps de pagamento do Android.
• Saiba como criar um app de pagamento baseado na Web no Guia do desenvolvedor de apps de pagamento baseados na Web.