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 integrados ao navegador pela primeira vez. Com os pagamentos na Web, a integração do comerciante com apps de pagamento fica mais simples, e a experiência do cliente fica mais simplificada e segura.

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

Neste artigo, mostramos como funciona uma transação de pagamento em um site de comerciante e 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 inicia o app de pagamento.

   

5. Se o cliente mudar algum detalhe (como opções de frete ou o endereço), o comerciante vai atualizar os detalhes da transação para refletir a mudança.

   

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 criando um objeto PaymentRequest. Esse objeto inclui informações importantes sobre a transação:

• Formas de pagamento aceitas e os dados delas para processar a transação.
• Detalhes, como o preço total (obrigatório) e informações sobre os itens.
• Opções em que os comerciantes podem solicitar informações de envio, como endereço de entrega e opção de envio.
• Os comerciantes também podem solicitar o endereço de faturamento, o nome, o e-mail e o número de telefone do pagador.
• Os comerciantes também podem incluir um tipo de frete (shipping, delivery ou pickup) opcional 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'
});

Como incluir um ID da transação

Alguns processadores de pagamento podem exigir que o comerciante forneça o ID da transação emitido com antecedência como parte das informações da transação. Uma integração típica inclui a comunicação entre o comerciante e o servidor do gerenciador de pagamentos para reservar o preço total. Isso impede que clientes mal-intencionados manipulem o preço e enganem o comerciante com uma validação no final da transação.

O comerciante pode transmitir um ID de transação como parte da propriedade data do objeto PaymentMethodData.

Fornecidas 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 de método de pagamento. Dessa forma, o navegador pode determinar o app de pagamento a ser iniciado assim que o comerciante estiver pronto para prosseguir com a transação.

Para saber como o processo de descoberta funciona em detalhes, consulte Configurar um método de pagamento.

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

Os comerciantes podem oferecer suporte a várias formas de pagamento, mas só devem apresentar os botões de pagamento que um cliente pode usar. Mostrar um botão de pagamento que não pode ser usado é uma experiência ruim para o usuário. Se um comerciante puder prever que um método de pagamento especificado no objeto PaymentRequest não vai funcionar para o cliente, ele poderá fornecer uma solução alternativa ou não mostrar o botão.

Usando uma instância PaymentRequest, um 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 retorna 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 o lançamento da interface de pagamento.

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

Como 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 para o método show(). O navegador vai 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 um argumento para show(), o navegador vai iniciar a interface de pagamento imediatamente.

Observação : se o gerenciador de pagamentos for projetado para retornar um ID da transação ao definir o preço total, o ID poderá ser transmitido como parte do resultado da promessa.

Etapa 4: o navegador inicia 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 iniciar.

A forma como o app de pagamento é criado é de responsabilidade do desenvolvedor, mas os eventos emitidos para e do 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 para o objeto PaymentRequest na etapa 1, que inclui 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 mudar os detalhes da transação, como a forma de pagamento e a opção de frete, no app de pagamento. Enquanto o cliente faz mudanças, o comerciante recebe os eventos de mudança e atualiza os detalhes da transação.

Há quatro tipos de eventos que um comerciante pode receber:

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

Evento de mudança da forma de pagamento

Um app de pagamento pode oferecer suporte a 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 mudança de forma de pagamento pode informar ao comerciante a nova forma de pagamento para que ele possa atualizar o preço total com o desconto e retornar ao app de pagamento.

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

Evento de mudança do endereço de entrega

Um app de pagamento pode fornecer o endereço de entrega do cliente. Isso é conveniente para os clientes, porque eles não precisam inserir detalhes manualmente em um formulário e podem armazenar o endereço de entrega nos apps de pagamento preferidos, em vez de em vários sites de comerciantes diferentes.

Se um cliente atualizar o endereço de entrega em um app de pagamento depois que a transação for iniciada, um evento 'shippingaddresschange' será enviado ao comerciante. Esse evento ajuda o comerciante a determinar o custo de frete com base no novo endereço, a atualizar o preço total e a retornar ao app de pagamento.

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

Se o comerciante não puder enviar 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.

Observação : os comerciantes não recebem o endereço de entrega completo dos clientes até que eles autorizem o pagamento.

Evento de mudança de 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 que o cliente pode selecionar. Exemplo:

• Frete padrão: sem custo financeiro
• Frete expresso: US$ 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 retornar ao app de pagamento.

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

O comerciante também pode modificar dinamicamente as opções de frete 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

Para mais segurança, um app de pagamento pode realizar uma validação do comerciante antes de prosseguir 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 informar ao comerciante o URL que ele pode usar para se validar.

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

Observação : o suporte para o evento de validação do comerciante é limitado ao Apple Safari. Os navegadores baseados no Chromium não implementaram esse evento desde maio de 2020.

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 ponto, 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 de credencial de pagamento retornado pelo app de pagamento. O comerciante pode usar a credencial para processar ou validar o pagamento. O processamento do pagamento é de responsabilidade do gerenciador de pagamentos.

Como concluir ou tentar novamente a transação

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

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

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 para a plataforma no guia para desenvolvedores de apps de pagamento Android.
• Aprenda a criar um app de pagamento baseado na Web no Guia para desenvolvedores de apps de pagamento baseados na Web.