Como adaptar seu app de pagamento baseado na Web ao Web Payments e proporcionar uma melhor experiência do usuário aos clientes.
Depois que um app de pagamento baseado na Web recebe uma solicitação de pagamento e inicia uma transação, o service worker atua como o hub de comunicação entre o comerciante e o app de pagamento. Nesta postagem, explicamos como um app de pagamento pode transmitir informações sobre a forma de pagamento, o endereço de entrega ou os dados de contato para o comerciante usando 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.
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 baseada na Web do Cliente A tem dois cartões de crédito e uma conta bancária registrada. Nesse caso, o app processa três
instrumentos de pagamento (****1234
, ****4242
, ******123
) e duas formas
de pagamento (emissor do cartão de crédito 1 e banco X). Em uma transação de pagamento, o aplicativo de pagamento pode permitir que o cliente escolha um dos instrumentos de pagamento e use-o para pagar o comerciante.
O app de pagamento pode informar ao comerciante qual forma de pagamento o cliente escolheu antes de enviar a resposta de pagamento completa. Isso é útil quando o comerciante quer exibir 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 um evento de "alteração na forma de pagamento" ao comerciante por meio de um service worker para notificar o novo identificador da forma de pagamento. O service worker precisa invocar
PaymentRequestEvent.changePaymentMethod()
com as novas informações da forma de
pagamento.
Os apps de pagamento podem transmitir um objeto methodDetails
como o segundo argumento opcional
de PaymentRequestEvent.changePaymentMethod()
. Esse objeto pode conter detalhes arbitrários da forma de pagamento necessários para que o comerciante processe o evento de alteração.
[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
da API Payment
Request, ele pode atualizar os detalhes de pagamento e responder com um
objeto
PaymentDetailsUpdate
.
[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 responder, a promessa que PaymentRequestEvent.changePaymentMethod()
retornou será resolvida com um objeto PaymentRequestDetailsUpdate
.
[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 IU no front-end. Consulte Refletir os detalhes de pagamento atualizados.
Informar o comerciante sobre uma mudança no endereço de entrega
Os 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 de dados padrão, o comerciante pode esperar receber endereços de entrega em uma estrutura consistente.
Além disso, os clientes podem registrar as informações de endereço no app de pagamento de sua preferência e reutilizá-las para diferentes comerciantes.
Os apps de pagamento podem fornecer uma interface para editar um endereço de entrega ou selecionar informações de endereço pré-registradas para o cliente em uma transação de pagamento. Quando um endereço de entrega é determinado temporariamente, o app de pagamento pode informar o comerciante sobre as informações de endereço editadas. Isso oferece vários benefícios aos comerciantes:
- Um comerciante pode determinar se o cliente atende à restrição regional para enviar o item (por exemplo, apenas nacional).
- Um comerciante pode alterar a lista de opções de frete com base na região do endereço de entrega (por exemplo, expresso internacional ou expresso).
- Um comerciante pode aplicar o novo custo de frete com base no endereço e atualizar o preço total.
Com a API Payment Handler, o app de pagamento pode enviar um evento de "alteração de endereço de entrega" ao comerciante do service worker para notificar o novo endereço de entrega. O service worker precisa invocar
PaymentRequestEvent.changeShippingAddress()
com o novo objeto de
endereço.
[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 receberá um evento shippingaddresschange
da API Payment Request para 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 responder, a promessa PaymentRequestEvent.changeShippingAddress()
retornada será resolvida com um objeto PaymentRequestDetailsUpdate
.
[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 IU no front-end. Consulte Refletir os detalhes de pagamento atualizados.
Informar o comerciante sobre uma mudança na opção de frete
As opções de envio são 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 seu próprio custo. Normalmente, os 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 app de pagamento. O app de pagamento pode usar as informações para criar uma interface e permitir que o cliente escolha uma opção de frete.
A lista de opções de frete especificadas na API Payment Request 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 foi escolhida pelo cliente. Isso é importante para o comerciante e o cliente, porque a alteração da 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 do pagamento, e o cliente também precisa estar ciente da mudança.
Com a API Payment Handler, o app de pagamento pode enviar um evento de "alteração na opção de frete" ao comerciante a partir do service worker. O service worker precisa
invocar
PaymentRequestEvent.changeShippingOption()
com o novo ID da 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
da API Payment Request. O comerciante precisa usar as informações para atualizar o preço total e responder com o PaymentDetailsUpdate
atualizado.
[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 responder, a promessa que PaymentRequestEvent.changeShippingOption()
retornou será resolvida com um objeto PaymentRequestDetailsUpdate
.
[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 IU no front-end. Consulte Refletir os detalhes de pagamento atualizados.
Os detalhes da forma de pagamento atualizados
Quando o comerciante terminar de atualizar os detalhes de pagamento, as promessas retornadas de .changePaymentMethod()
, .changeShippingAddress()
e .changeShippingOption()
serão resolvidas com um objeto PaymentRequestDetailsUpdate
comum. O gerenciador de pagamentos pode usar o resultado para refletir as opções atualizadas de preço total e envio na IU.
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 com suporte.
- O endereço de entrega contém informações inválidas.
- A opção de frete não pode ser selecionada para o endereço de entrega fornecido ou por algum outro motivo.
Use as propriedades a seguir para refletir o status do erro:
error
: string de erro legível por humanos. Essa é a melhor string para exibir aos clientes.shippingAddressErrors
: objetoAddressErrors
que contém uma string de erro detalhada por propriedade de endereço. Isso é útil se você quer abrir um formulário que permite que o cliente edite o endereço e precisa apontá-lo diretamente para os campos inválidos.paymentMethodErrors
: objeto de erro específico da forma de pagamento. Você pode pedir aos comerciantes que forneçam um erro estruturado, mas os autores das especificações da Web Payments recomendam manter uma string simples.
Exemplo de código
A maioria dos exemplos de código que você encontrou neste documento são trechos do seguinte app de exemplo:
https://paymenthandler-demo.glitch.me
[gerenciador de pagamentos] service worker
[Gerenciador de pagamentos] Front-end
Para testar, faça o seguinte:
- Acesse https://paymentrequest-demo.glitch.me/.
- Acesse a parte inferior da página.
- Pressione Adicionar um botão de pagamento.
- Insira
https://paymenthandler-demo.glitch.me
no campo Identificador da forma de pagamento. - Pressione o botão Pagar ao lado do campo.