Saiba como os comerciantes integram apps de pagamento e como as transações de pagamento funcionam com a API Payment Request.
As APIs Web Payments são recursos de pagamento dedicados integrados ao navegador pela primeira vez. Com a Web Payments, a integração do comerciante com apps de pagamento fica mais simples, e a experiência do cliente se torna mais simplificada e segura.
Para saber mais sobre os benefícios de usar a Web Payments, confira Como capacitar apps de pagamento com a Web Payments.
Este artigo mostra uma transação de pagamento em um site de comerciante e ajuda a entender como funciona a integração de 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 mudar algum detalhe (como as opções de frete ou o endereço), o comerciante vai atualizar os detalhes da transação para refletir a mudança.
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 aceitáveis 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 frete, como um endereço e uma opção de frete.
- 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 o tipo de frete opcional (
shipping,deliveryoupickup) noPaymentRequest. O app de pagamento pode usar isso como uma dica para exibir 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'
});
Alguns gerenciadores de pagamento podem exigir que o comerciante forneça o ID da transação que emitiram com antecedência como parte das informações da transação. Uma integração típica inclui a comunicação entre o servidor do comerciante e o do processador 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.
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 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, confira Como configurar uma forma de pagamento.
Etapa 2: o comerciante mostra um botão de pagamento
Os comerciantes podem aceitar várias formas de pagamento, mas só devem apresentar os botões de pagamento
daquelas que o cliente pode realmente 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 uma
forma de pagamento especificada no objeto PaymentRequest não vai funcionar para o
cliente, ele poderá fornecer uma solução alternativa ou não mostrar esse 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 que aceita a
forma de pagamento foi descoberto e que o app de pagamento específico da plataforma está 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, recuperado de um servidor), o comerciante pode adiar o lançamento da IU de pagamento até que o 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 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 argumento para show(), o navegador vai
iniciar a interface de pagamento imediatamente.
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 depende, em grande parte, do desenvolvedor, 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 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 as 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 na forma de pagamento
- Evento de mudança de endereço de entrega
- Evento de mudança na opção de frete
- Evento de validação do comerciante
Evento de mudança na 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 cobrir esse caso de uso, o evento de mudança na 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 retorná-lo ao app de pagamento.
request.addEventListener('paymentmethodchange', e => {
e.updateWith({
// Add discount etc.
});
});
Evento de mudança de 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 manualmente nenhum detalhe 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 após o início da transação, um evento 'shippingaddresschange' será enviado ao comerciante. Esse evento ajuda o comerciante a determinar o custo de frete com base
no novo endereço, atualizar o preço total e retornar o valor 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á fornecer uma mensagem de erro adicionando um parâmetro de erro aos detalhes da transação retornados ao app de pagamento.
Evento de mudança na 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,00
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 de frete, atualizar o preço total e retornar o valor para o
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 conjuntos diferentes de opções de frete para clientes nacionais e internacionais.
Evento de validação do comerciante
Para maior 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 fica a critério 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
});
});
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 como 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 vai 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. A forma como esse processo crítico funciona depende do gerenciador de pagamentos.
Concluir ou tentar novamente a transação
Depois que o comerciante determinar se a transação foi concluída ou falhou, ele poderá:
- 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 uma plataforma no guia para desenvolvedores de apps de pagamento Android.
- Saiba como criar um app de pagamento baseado na Web no guia para desenvolvedores de apps de pagamento baseados na Web.