Como adaptar seu app de pagamento baseado na Web para o Web Payments e oferecer uma melhor experiência do usuário aos clientes.
Quando um app de pagamento baseado na Web recebe uma solicitação e inicia um pagamento transação, o service worker vai agir como o hub de comunicação entre o comerciante e o app de pagamento. Esta postagem explica como um app de pagamento pode transmitir informações sobre a forma de pagamento, endereço de entrega ou informações de contato ao comerciante usando um service worker.
![Como processar informações de pagamento opcionais com um service worker](https://web.dev/static/articles/handling-optional-payment-information/image/handling-optional-payment-9e082afff222b.png?authuser=6&hl=pt)
Informar o comerciante sobre uma mudança na forma de pagamento
Os apps de pagamento aceitam vários instrumentos de pagamento com diferentes formas de pagamento.
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 do cliente A baseada na Web tem dois créditos
e uma conta bancária registrada. Nesse caso, o app processa três
instrumentos de pagamento (****1234
, ****4242
, ******123
) e dois pagamentos
(emissor do cartão de crédito 1 e Banco X). Em uma transação de pagamento, o valor
aplicativo pode permitir que o cliente escolha um dos instrumentos de pagamento e o use para pagar
para o comerciante.
![interface do seletor de forma de pagamento](https://web.dev/static/articles/handling-optional-payment-information/image/payment-method-picker-ui-83cf9bfe052f4.png?authuser=6&hl=pt)
O app de pagamento pode informar ao comerciante qual forma de pagamento o cliente usa. selecionados antes de enviar a resposta de pagamento completa. Isso é útil quando o comerciante quer veicular 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 uma "alteração da forma de pagamento"
evento ao comerciante por meio de um service worker para notificar a nova forma de pagamento
identificador. O service worker deve invocar
PaymentRequestEvent.changePaymentMethod()
com a nova forma de pagamento
informações imprecisas ou inadequadas.
![Informar o comerciante sobre uma mudança na forma de pagamento](https://web.dev/static/articles/handling-optional-payment-information/image/inform-merchant-a-payme-9ae9bd3b7b774.png?authuser=6&hl=pt)
Apps de pagamento podem transmitir um objeto methodDetails
como o segundo argumento opcional
para PaymentRequestEvent.changePaymentMethod()
. Esse objeto pode conter
detalhes arbitrários da forma de pagamento necessários para o comerciante processar a mudança
evento.
[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
do recurso de pagamento
Request, ele pode atualizar os detalhes de pagamento e responder com uma
PaymentDetailsUpdate
objeto.
[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 responde, prometer que
PaymentRequestEvent.changePaymentMethod()
retornados resolverão com uma
PaymentRequestDetailsUpdate
objeto.
[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 interface no front-end. Consulte Reflita sobre o detalhes de pagamento.
Informar o comerciante sobre uma mudança no endereço de entrega
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 padrão formato de dados, os o comerciante receberá endereços de entrega em uma estrutura consistente.
Além disso, os clientes podem registrar suas informações de endereço no e reutilizá-lo para comerciantes diferentes.
![Interface do seletor de endereço de entrega](https://web.dev/static/articles/handling-optional-payment-information/image/shipping-address-picker-u-2f452a9725ce3.png?authuser=6&hl=pt)
Os apps de pagamento podem fornecer uma interface para editar um endereço de entrega ou selecionar informações de endereço pré-registradas do cliente em uma transação de pagamento. Quando um endereço de entrega é determinado temporariamente, o aplicativo de pagamento pode permitir que o o comerciante tenha conhecimento das informações de endereço encobertas. Isso oferece aos comerciantes vários benefícios:
- Um comerciante pode determinar se o cliente atende à restrição regional para enviar o item (por exemplo, somente para o país).
- Um comerciante pode mudar a lista de opções de envio com base na região do endereço de entrega (por exemplo, regular internacional ou expresso).
- O comerciante pode aplicar o novo custo de frete com base no endereço e atualizar os preço total.
Com a API Payment Handler, o app de pagamento pode enviar um "endereço de entrega"
alterar" evento ao comerciante pelo service worker para notificar o novo envio
endereço IP. O service worker deve invocar
PaymentRequestEvent.changeShippingAddress()
com o novo endereço
objeto.
![Informar o comerciante sobre uma mudança no endereço de entrega](https://web.dev/static/articles/handling-optional-payment-information/image/inform-merchant-a-shipp-414e5048c9eb4.png?authuser=6&hl=pt)
[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 recebe um evento shippingaddresschange
na guia
Solicite a API para que possam 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 responde,
PaymentRequestEvent.changeShippingAddress()
retornados resolverão com uma
PaymentRequestDetailsUpdate
objeto.
[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 interface no front-end. Consulte Reflita sobre o detalhes de pagamento.
Informar o comerciante sobre uma mudança na opção de frete
As opções de frete são os 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 um custo. Normalmente, 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 pagamento app. O aplicativo de pagamento pode usar as informações para construir uma interface e permitir que o o cliente escolhe a opção de envio.
![Interface do seletor de opção de frete](https://web.dev/static/articles/handling-optional-payment-information/image/shipping-option-picker-ui-a337c6acfbf94.png?authuser=6&hl=pt)
A lista de opções de envio especificadas na Payment Request API 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 o cliente escolhidos. Isso é importante para o comerciante e para o cliente, porque alterar a 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 de pagamento posteriormente e a o cliente também precisa estar ciente da mudança.
Com a API Payment Handler, o aplicativo de pagamento pode enviar uma "opção de envio
alterar" para o comerciante a partir do service worker. O service worker precisa
invocar
PaymentRequestEvent.changeShippingOption()
pelo novo ID da opção de frete.
![Informar o comerciante sobre uma mudança na opção de frete](https://web.dev/static/articles/handling-optional-payment-information/image/inform-merchant-a-shipp-8f67c21bfb63e.png?authuser=6&hl=pt)
[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
na guia
API Request. O comerciante precisa usar as informações para atualizar o preço total.
e responder com a versão
PaymentDetailsUpdate
[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 responde, prometer que
PaymentRequestEvent.changeShippingOption()
retornados resolverão com uma
PaymentRequestDetailsUpdate
objeto.
[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 interface no front-end. Consulte Reflita sobre o detalhes de pagamento.
Mostre os detalhes de pagamento atualizados.
Quando o comerciante terminar de atualizar os detalhes de pagamento, as promessas serão retornadas
de .changePaymentMethod()
, .changeShippingAddress()
e
.changeShippingOption()
resolverá com uma
PaymentRequestDetailsUpdate
objeto. O gerenciador de pagamento pode usar o resultado para refletir o preço total atualizado.
e opções de envio para a interface.
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 aceitas.
- O endereço de entrega contém informações inválidas.
- A opção de envio não pode ser selecionada para o endereço de entrega fornecido ou por algum outro motivo.
Use as seguintes propriedades para refletir o status do erro:
error
: string de erro legível por humanos. Esta é a melhor string para exibir para os clientes.shippingAddressErrors
AddressErrors
Objeto que contém uma string de erro detalhada por propriedade de endereço. Isso é útil se você quiser abrir um formulário que permite ao cliente editar o endereço e você precisa apontá-los diretamente para os campos inválidos.paymentMethodErrors
: objeto de erro específico da forma de pagamento. Você pode pedir comerciantes forneçam um erro estruturado, mas os autores da especificação Web Payments recomendamos mantê-lo como uma string simples.
Código de amostra
A maioria dos exemplos de código que você viu neste documento foi trechos do seguinte App de exemplo funcional:
https://paymenthandler-demo.glitch.me
service worker [gerenciador de pagamentos]
Front-end [gerenciador de pagamentos]
Para testar:
- Acesse https://paymentrequest-demo.glitch.me/ (link em inglês).
- Acesse a parte inferior da página.
- Pressione o botão Adicionar um pagamento.
- Insira
https://paymenthandler-demo.glitch.me
no campo Identificador da forma de pagamento. - Pressione o botão Pagar ao lado do campo.