Como orquestrar transações de pagamento com um service worker

Como adaptar seu app de pagamento baseado na Web ao Web Payments e proporcionar uma melhor experiência do usuário aos clientes.

Eiji Kitamura

Depois que o app de pagamento for registrado, você poderá aceitar solicitações de pagamento de comerciantes. Nesta postagem, explicamos como orquestrar uma transação de pagamento de um service worker durante o ambiente de execução, ou seja, quando uma janela é exibida e o usuário está interagindo com ela.

"Alterações de parâmetros de pagamento do tempo de execução" referem-se a um conjunto de eventos que permite que o comerciante e o gerenciador de pagamento troquem mensagens enquanto o usuário interage com o gerenciador de pagamentos. Saiba mais em Como lidar com informações de pagamento opcionais com um service worker.

Receber um evento de solicitação de pagamento do comerciante.

Quando um cliente escolhe pagar com seu app de pagamento baseado na Web e o comerciante invoca PaymentRequest.show(), seu service worker recebe um evento paymentrequest. Adicione um listener de eventos ao service worker para capturar o evento e se preparar para a próxima ação.

[payment gerenciador] service-worker.js:

…
let payment_request_event;
let resolver;
let client;

// `self` is the global object in service worker
self.addEventListener('paymentrequest', async e => {
  if (payment_request_event) {
    // If there's an ongoing payment transaction, reject it.
    resolver.reject();
  }
  // Preserve the event for future use
  payment_request_event = e;
…

O PaymentRequestEvent preservado contém informações importantes sobre essa transação:

Abra a janela do gerenciador de pagamentos para exibir o front-end do app de pagamento baseado na Web

Quando um evento paymentrequest é recebido, o app de pagamento pode abrir uma janela do gerenciador de pagamentos chamando PaymentRequestEvent.openWindow(). A janela do gerenciador de pagamentos apresentará aos clientes a interface do app de pagamento, em que eles podem autenticar, escolher o endereço e as opções de entrega e autorizar o pagamento. Veremos como escrever o código de front-end em Como processar pagamentos no front-end de pagamento (em breve).

Transmita uma promessa preservada para PaymentRequestEvent.respondWith() para que seja possível resolvê-la com um resultado de pagamento no futuro.

[payment gerenciador] service-worker.js:

…
self.addEventListener('paymentrequest', async e => {
…
  // Retain a promise for future resolution
  // Polyfill for PromiseResolver is provided below.
  resolver = new PromiseResolver();

  // Pass a promise that resolves when payment is done.
  e.respondWith(resolver.promise);
  // Open the checkout page.
  try {
    // Open the window and preserve the client
    client = await e.openWindow(checkoutURL);
    if (!client) {
      // Reject if the window fails to open
      throw 'Failed to open window';
    }
  } catch (err) {
    // Reject the promise on failure
    resolver.reject(err);
  };
});
…

É possível usar um polyfill PromiseResolver conveniente para resolver uma promessa a tempo arbitrário.

class PromiseResolver {
  constructor() {
    this.promise_ = new Promise((resolve, reject) => {
      this.resolve_ = resolve;
      this.reject_ = reject;
    })
  }
  get promise() { return this.promise_ }
  get resolve() { return this.resolve_ }
  get reject() { return this.reject_ }
}

Trocar informações com o front-end

O service worker do app de pagamento pode trocar mensagens com o front-end dele usando ServiceWorkerController.postMessage(). Para receber mensagens do front-end, detecte eventos message.

[payment gerenciador] service-worker.js:

// Define a convenient `postMessage()` method
const postMessage = (type, contents = {}) => {
  if (client) client.postMessage({ type, ...contents });
}

Receber o indicador "Pronto" do front-end

Depois que a janela do gerenciador de pagamentos é aberta, o service worker precisa aguardar um sinal de estado pronto do front-end do app de pagamento. Ele pode transmitir informações importantes para o front-end quando estiver pronto.

front-end de [gerenciador de pagamento]:

navigator.serviceWorker.controller.postMessage({
  type: 'WINDOW_IS_READY'
});

[payment gerenciador] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      // `WINDOW_IS_READY` is a frontend's ready state signal
      case 'WINDOW_IS_READY':
        const { total } = payment_request_event;
…

Transmitir os detalhes da transação para o front-end

Agora envie os detalhes do pagamento de volta. Nesse caso, você está enviando apenas o total da solicitação de pagamento, mas pode enviar mais detalhes, se quiser.

[payment gerenciador] service-worker.js:

…
        // Pass the payment details to the frontend
        postMessage('PAYMENT_IS_READY', { total });
        break;
…

front-end de [gerenciador de pagamento]:

let total;

navigator.serviceWorker.addEventListener('message', async e => {
  switch (e.data.type) {
      case 'PAYMENT_IS_READY':
        ({ total } = e.data);
        // Update the UI
        renderHTML(total);
        break;
…

Retornar as credenciais de pagamento do cliente

Quando o cliente autoriza o pagamento, o front-end pode enviar uma pós-mensagem ao service worker para prosseguir. Resolva a promessa transmitida a PaymentRequestEvent.respondWith() para enviar o resultado de volta ao comerciante. Transmita um objeto PaymentHandlerResponse.

front-end de [gerenciador de pagamento]:

  const paymentMethod = …

  postMessage('PAYMENT_AUTHORIZED', {
    paymentMethod,              // Payment method identifier
  });

[payment gerenciador] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_AUTHORIZED':
        // Resolve the payment request event promise
        // with a payment response object
        const response = {
          methodName: e.data.paymentMethod,
          details: { id: 'put payment credential here' },
        }
        resolver.resolve(response);
        // Don't forget to initialize.
        payment_request_event = null;
        break;
      …

Cancelar a transação de pagamento

Para permitir que o cliente cancele a transação, o front-end pode enviar uma mensagem posta ao service worker para fazer isso. Ele pode resolver a promessa passada para PaymentRequestEvent.respondWith() com null para indicar ao comerciante que a transação foi cancelada.

front-end de [gerenciador de pagamento]:

  postMessage('CANCEL_PAYMENT');

[payment gerenciador] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'CANCEL_PAYMENT':
        // Resolve the payment request event promise
        // with null
        resolver.resolve(null);
        // Don't forget to initialize.
        payment_request_event = null;
        break;
      …

Exemplo de código

Todos os exemplos de código que você viu neste documento são trechos do seguinte app de exemplo em funcionamento:

https://paymenthandler-demo.glitch.me

[gerenciador de pagamentos] service worker

[Gerenciador de pagamentos] Front-end

Para testar, faça o seguinte:

1. Acesse https://paymentrequest-demo.glitch.me/.
2. Acesse a parte inferior da página.
3. Pressione Adicionar um botão de pagamento.
4. Insira https://paymenthandler-demo.glitch.me no campo Identificador da forma de pagamento.
5. Pressione o botão Pagar ao lado do campo.

Próximas etapas

Neste artigo, aprendemos como orquestrar uma transação de pagamento com um service worker. A próxima etapa é aprender a adicionar mais recursos avançados ao service worker.

• Como processar informações de pagamento opcionais com um service worker