Esta página foi traduzida pela API Cloud Translation.

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

Para saber mais sobre os benefícios de usar o Web Payments, confira Capacitação apps de pagamento com o Web Payments.

Neste artigo, explicamos como fazer um pagamento no site da loja e ajuda você a entender como funciona a integração com apps de pagamento.

O processo envolve seis etapas:

O comerciante inicia uma transação de pagamento.
O comerciante mostra um botão de pagamento.
O cliente pressiona o botão de pagamento.
O navegador inicia o app de pagamento.
Se o cliente alterar algum detalhe (como opções de envio ou endereço), o comerciante atualiza os detalhes da transação refletindo a alteração.
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 o pagamento. transação construindo uma PaymentRequest objeto. 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 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 frete e uma opção de envio.
Os comerciantes também podem solicitar o endereço de faturamento, o nome do pagador, e-mail número de telefone.
Os comerciantes também podem incluir frete opcional tipo (shipping, delivery ou pickup) em PaymentRequest. 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'
});

Incluir um ID da transação

Alguns gerenciadores de pagamento podem exigir que o comerciante informe o ID da transação emitidos com antecedência como parte das informações da transação. Um a integração típica inclui a comunicação entre as para reservar o preço total. Isso evita problemas os clientes de manipular o preço e enganar o comerciante validação no final da transação.

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

Com as informações da transação, o navegador passa por uma descoberta processo de pagamento dos apps especificados nos PaymentRequest com base no pagamento identificadores de método. Dessa forma, o navegador pode determinar o app de pagamento seja lançado assim que o comerciante estiver pronto para prosseguir com a transação.

Para saber como funciona o processo de descoberta, confira Como configurar um pagamento método.

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

Os comerciantes aceitam várias formas de pagamento, mas apenas a forma de pagamento deve ser apresentada. para aqueles que um cliente pode realmente usar. Mostrar um botão de pagamento inutilizável é uma experiência do usuário ruim. Se um comerciante conseguir prever forma de pagamento especificada no objeto PaymentRequest não vai funcionar para o ele poderá oferecer uma solução substituta ou não exibir esse botão.

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

O cliente tem o app de pagamento disponível?

A canMakePayment() O método 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 é descoberta e se o app de pagamento específico da plataforma está instalado ou o aplicativo de pagamento baseado na web está pronto para ser registrados.

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 show() da instância PaymentRequest que aciona imediatamente o lançamento do a interface de pagamento.

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

Adiar o lançamento da interface de pagamento

Veja uma demonstração de adiamento do pagamento interface até que o preço total final seja determinados.

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

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 promessa especificada como argumento para show(), o navegador iniciar a interface de pagamento imediatamente.

Etapa 4: o navegador inicia o app de pagamento

O navegador pode iniciar um aplicativo de pagamento específico da plataforma ou baseado na web. Saiba mais sobre como o Chrome determina qual app de pagamento lançamento).

A forma como o aplicativo de pagamento é criada cabe ao desenvolvedor na maior parte, mas o 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 a transação informações transmitidos ao 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 o pagamento e a opção de envio no app de pagamento. Enquanto o cliente faz alterações, 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 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 uma um desconto especial, dependendo da seleção do cliente. Para abordar esse caso de uso, o evento de mudança da forma de pagamento pode informar o comerciante sobre o novo pagamento. para que possam 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 pode fornecer o endereço de entrega do cliente. Isso é conveniente para os clientes, porque eles não precisam inserir detalhes em um formulário e podem armazenar o endereço de entrega no método de pagamento em vez de vários sites de comerciantes.

Se um cliente atualizar o endereço de entrega em um app de pagamento após o transação for iniciada, um evento 'shippingaddresschange' será enviado para o comerciante. Esse evento ajuda o comerciante a determinar o custo de 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 puder enviar para o endereço atualizado, ele poderá exibir um 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 envio são exibidas como uma lista preços e nomes de serviços que o cliente pode escolher. Exemplo:

Frete padrão - Sem custo financeiro
Frete expresso: US$ 5,00

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

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

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

Evento de validação do comerciante

Para mais segurança, um app de pagamento pode validar o comerciante antes de prosseguir para o fluxo de pagamento. O design do mecanismo de validação depende o app de pagamento, mas o evento de validação do comerciante serve para informar o comerciante do URL que podem usar para se validarem.

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 autorizar o pagamento, o método show() retorna uma promessa que se resolve 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 usuário do navegador ainda pode mostrar um indicador de carregamento, o que significa que a transação ainda não estiver concluída.

Se o aplicativo de pagamento for encerrado devido a uma falha ou erro no pagamento, o promessa retornada de show() é rejeitada, e o navegador encerra o pagamento transação.

Processando e validando o pagamento

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

Concluir ou repetir a transação

Depois que o comerciante determinar se a transação foi bem-sucedida ou falhou, é possível:

Chame o método .complete() para concluir a transação e dispensar a 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 Como configurar uma forma de pagamento.
Saiba como criar um app de pagamento específico para a plataforma no Guia do desenvolvedor de apps de pagamento para Android.
Saiba como criar um app de pagamento baseado na Web na página do desenvolvedor de apps de pagamento guia.