Como adaptar seu app de pagamento baseado na Web aos pagamentos da Web e oferecer uma melhor experiência do usuário aos clientes.
Quando um app de pagamento baseado na Web recebe uma solicitação de pagamento e inicia uma transação de pagamento, o worker de serviço atua 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, o endereço de entrega ou os dados de contato para o comerciante usando um worker de serviço.
Informar ao comerciante sobre uma mudança na forma de pagamento
Os apps de pagamento podem oferecer suporte a vários instrumentos de pagamento com formas de pagamento diferentes.
| 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 da Web do Cliente A tem dois cartões de crédito e uma conta bancária registrados. Nesse caso, o app está processando três
instrumentos de pagamento (****1234, ****4242, ******123) e dois métodos de
pagamento (emissor de cartão de crédito 1 e banco X). Em uma transação de pagamento, o app de pagamento
pode permitir que o cliente escolha um dos instrumentos de pagamento e o use para pagar
ao 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 merchant quer veicular uma campanha de desconto 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 da forma de pagamento"
ao comerciante usando um worker de serviço para notificar o novo identificador da forma de pagamento. O worker de serviço 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
para PaymentRequestEvent.changePaymentMethod(). Esse objeto pode conter
detalhes arbitrários da forma de pagamento necessários para que o comerciante processe o evento
de mudança.
[payment handler] 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.
[merchant]
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, a promessa que
PaymentRequestEvent.changePaymentMethod()
retorna será resolvida com um objeto
PaymentRequestDetailsUpdate.
[payment handler] 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 Refletir os detalhes de pagamento atualizados.
Informar ao 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 coleta de endereços a apps de pagamento. Como os dados do endereço serão fornecidos no formato 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 preferido 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 do cliente em uma transação de pagamento. Quando um endereço de entrega é determinado temporariamente, o app de pagamento pode informar ao comerciante as informações do endereço editado. 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, apenas no país).
- Um comerciante pode mudar a lista de opções de frete com base na região do endereço de entrega (por exemplo, internacional normal 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 "mudança de endereço
de entrega" ao comerciante pelo worker de serviço para notificar o novo endereço
de entrega. O worker do serviço precisa invocar
PaymentRequestEvent.changeShippingAddress()
com o novo objeto de
endereço.
[payment handler] 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 vai receber um evento shippingaddresschange da API Payment Request para responder com o PaymentDetailsUpdate atualizado.
[merchant]
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, a promessa
PaymentRequestEvent.changeShippingAddress()
retornada é resolvida com um objeto
PaymentRequestDetailsUpdate.
[payment handler] 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 Refletir os detalhes de pagamento atualizados.
Informar ao 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 de envio comuns incluem:
- Frete grátis
- Frete expresso
- Frete internacional
- Frete internacional premium
Cada um tem um custo próprio. 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 especificada na API Payment Request do comerciante é
propagada para o worker de serviço do app de pagamento como uma propriedade de
PaymentRequestEvent.
[merchant]
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 frete o cliente escolheu. Isso é importante para o comerciante e o cliente porque mudar a opção de frete também muda o preço total. O comerciante precisa ser informado sobre o preço mais recente para a verificação de pagamento mais tarde, 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 "mudança de opção de
frete" ao comerciante pelo worker de serviço. O worker do serviço precisa
invocar
PaymentRequestEvent.changeShippingOption()
com o novo ID da opção de frete.
[payment handler] 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 vai receber 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.
[merchant]
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, a promessa que
PaymentRequestEvent.changeShippingOption()
retorna será resolvida com um objeto
PaymentRequestDetailsUpdate.
[payment handler] 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 Refletir os detalhes de pagamento atualizados.
Refletir os detalhes de pagamento atualizados
Quando o comerciante terminar de atualizar os detalhes do 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 o preço total atualizado
e as opções de frete na interface.
Os comerciantes podem retornar erros por alguns motivos:
- A forma de pagamento não é aceitável.
- 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 mostrar aos clientes.shippingAddressErrors: objetoAddressErrorsque contém a string de erro detalhada por propriedade de endereço. Isso é útil se você quiser abrir um formulário que permita que o cliente edite o endereço e precisar apontar diretamente para os campos inválidos.paymentMethodErrors: objeto de erro específico do método de pagamento. Você pode pedir que os comerciantes forneçam um erro estruturado, mas os autores da especificação do Web Payments recomendam manter uma string simples.
Código de amostra
A maioria dos códigos de exemplo que você viu neste documento foram trechos do app de exemplo funcional a seguir:
https://paymenthandler-demo.glitch.me
[payment handler] service worker
[payment handler] frontend
Para testar:
- Acesse https://paymentrequest-demo.glitch.me/.
- Acesse a parte inferior da página.
- Clique no botão Adicionar uma forma de pagamento.
- Insira
https://paymenthandler-demo.glitch.meno campo Identificador da forma de pagamento. - Pressione o botão Pagar ao lado do campo.