Como configurar uma forma de pagamento

Uma transação de pagamento usando o Web Payments começa com a descoberta do seu app de pagamento. Saiba como configurar uma forma de pagamento e deixar seu app preparado para comerciantes e clientes fazerem pagamentos.

Eiji Kitamura

Para ser usado com a API Payment Request, um app de pagamento precisa estar associado a um identificador de forma de pagamento. Os comerciantes que quiserem fazer a integração com um app de pagamento usarão o identificador da forma de pagamento para indicar isso ao navegador. Este artigo discute como funciona a descoberta de apps de pagamento e como configurar esse app para que ele seja descoberto e invocado corretamente por um navegador.

Se você não conhece o conceito de Web Payments ou o funcionamento de uma transação de pagamento por apps de pagamento, leia os seguintes artigos primeiro:

• Capacitação de apps de pagamento com o Web Payments
• O ciclo de uma transação de pagamento

Suporte ao navegador

O Web Payments consiste em algumas tecnologias diferentes, e o status do suporte depende do navegador.

Como um navegador descobre um app de pagamento

Todo app de pagamento precisa fornecer o seguinte:

• Identificador da forma de pagamento com base no URL
• Manifesto da forma de pagamento (exceto quando o identificador da forma de pagamento é fornecido por terceiros)
• Manifesto de app da Web

O processo de descoberta começa quando um comerciante inicia uma transação:

1. O navegador envia uma solicitação para o URL do identificador da forma de pagamento e busca o manifesto da forma de pagamento.
2. O navegador determina o URL do manifesto do app da Web no manifesto da forma de pagamento e busca esse manifesto.
3. O navegador determina se o app de pagamento do SO ou o app de pagamento baseado na Web será iniciado a partir do manifesto do app da Web.

As próximas seções explicam em detalhes como configurar sua própria forma de pagamento para que os navegadores possam encontrá-la.

Etapa 1: fornecer o identificador da forma de pagamento

Um identificador da forma de pagamento é uma string baseada em URL. Por exemplo, o identificador do Google Pay é https://google.com/pay. Os desenvolvedores de apps de pagamento podem escolher qualquer URL como identificador da forma de pagamento, desde que tenham controle sobre ele e possam veicular conteúdo arbitrário. Neste artigo, usaremos https://bobbucks.dev/pay como o identificador da forma de pagamento.

Como os comerciantes usam o identificador da forma de pagamento

Um objeto PaymentRequest é criado com uma lista de identificadores de forma de pagamento que identifica os apps de pagamento que um comerciante decide aceitar. Os identificadores da forma de pagamento são definidos como um valor para a propriedade supportedMethods. Exemplo:

[comerciante] solicita pagamento:

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay'
}], {
  total: {
    label: 'total',
    amount: { value: '10', currency: 'USD' }
  }
});

Etapa 2: veicular o manifesto da forma de pagamento

Um manifesto da forma de pagamento é um arquivo JSON que define qual app de pagamento pode usar essa forma de pagamento.

Fornecer o manifesto da forma de pagamento

Quando um comerciante inicia uma transação de pagamento, o navegador envia uma solicitação HTTP GET para o URL do identificador da forma de pagamento. O servidor responde com o corpo do manifesto da forma de pagamento.

O manifesto de uma forma de pagamento tem dois campos, default_applications e supported_origins.

Um arquivo de manifesto de forma de pagamento vai ficar assim:

[gerenciador de pagamentos] /payment-manifest.json:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": [
    "https://alicepay.friendsofalice.example"
  ]
}

Quando o navegador lê o campo default_applications, ele encontra uma lista de links para manifestos de apps da Web de apps de pagamento compatíveis.

Como alternativa, encaminhe o navegador para encontrar o manifesto da forma de pagamento em outro local

O URL do identificador da forma de pagamento pode responder com um cabeçalho Link que aponta para outro URL em que o navegador pode buscar o manifesto da forma de pagamento. Isso é útil quando um manifesto de forma de pagamento está hospedado em um servidor diferente ou quando o app de pagamento é disponibilizado por terceiros.

Configure o servidor da forma de pagamento para responder com um cabeçalho HTTP Link com o atributo rel="payment-method-manifest" e o URL do manifesto da forma de pagamento.

Por exemplo, se o manifesto estiver em https://bobbucks.dev/payment-manifest.json, o cabeçalho de resposta vai incluir:

Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"

O URL pode ser um nome de domínio totalmente qualificado ou um caminho relativo. Inspecione https://bobbucks.dev/pay/ do tráfego de rede para ver um exemplo. Também é possível usar um comando curl:

curl --include https://bobbucks.dev/pay

Etapa 3: exibir um manifesto de app da Web

Um manifesto de app da Web é usado para definir um app da Web como o nome sugere. Ele é um arquivo de manifesto amplamente utilizado para definir um Progressive Web App (PWA).

O manifesto de app da Web típico seria assim:

[gerenciador de pagamentos] /manifest.json:

{
  "name": "Pay with Bobpay",
  "short_name": "Bobpay",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

As informações descritas em um manifesto de app da Web também são usadas para definir como um app de pagamento aparece na interface de solicitação de pagamento.

A propriedade name do manifesto do app da Web é usada como o nome do app de pagamento, e a propriedade icons é usada como o ícone do app de pagamento.

Como o Chrome determina qual app de pagamento iniciar

Iniciar o app de pagamento específico da plataforma

Para iniciar o app de pagamento específico da plataforma, as seguintes condições precisam ser atendidas:

• O campo related_applications é especificado no manifesto do app da Web e:
  • O ID do pacote e a assinatura do app instalado são correspondentes, enquanto a versão mínima (min_version) no manifesto do app da Web é menor ou igual à versão do app instalado.
• O campo prefer_related_applications é true.
• O app de pagamento específico da plataforma está instalado e tem:
  • Um filtro de intent de org.chromium.action.PAY.
  • Um identificador de forma de pagamento especificado como o valor da propriedade org.chromium.default_payment_method_name.

Confira os apps de pagamento para Android: guia para desenvolvedores para mais detalhes sobre como configurá-los.

[gerenciador de pagamentos] /manifest.json

"prefer_related_applications": true,
"related_applications": [{
  "platform": "play",
  "id": "xyz.bobpay.app",
  "min_version": "1",
  "fingerprints": [{
    "type": "sha256_cert",
    "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2:05:0A:1E:57:5F:23:40:E9:E3:87:14:EC:6D:A2:04:21:E0:FD:3B:D1"
  }]
}]

Se o navegador determinar que o app de pagamento específico da plataforma está disponível, o fluxo de descoberta será encerrado aqui. Caso contrário, segue para a próxima etapa: iniciar o app de pagamento baseado na Web.

Iniciar o app de pagamento baseado na Web

O app de pagamento baseado na Web precisa ser especificado no campo serviceworker do manifesto do app da Web.

[gerenciador de pagamentos] /manifest.json:

"serviceworker": {
  "src": "payment-handler.js"
}

O navegador inicia o app de pagamento baseado na Web enviando um evento paymentrequest para o service worker. O service worker não precisa ser registrado com antecedência. Ele pode ser registrado em tempo real.

Noções básicas sobre as otimizações especiais

Como os navegadores podem pular a interface de solicitação de pagamento e iniciar um app de pagamento diretamente

No Chrome, quando o método show() de PaymentRequest é chamado, a API Payment Request exibe uma interface fornecida pelo navegador chamada "IU de solicitação de pagamento". Essa interface permite que os usuários escolham um app de pagamento. Depois de pressionar o botão Continuar na interface da solicitação de pagamento, o app de pagamento selecionado é iniciado.

Mostrar a interface de solicitação de pagamento antes de iniciar um app de pagamento aumenta o número de etapas necessárias para um usuário concluir um pagamento. Para otimizar o processo, o navegador pode delegar o preenchimento dessas informações a apps de pagamento e iniciar um app de pagamento diretamente sem mostrar a interface de solicitação de pagamento quando show() for chamado.

Para iniciar um app de pagamento diretamente, as seguintes condições precisam ser atendidas:

• show() é acionado com um gesto do usuário (por exemplo, um clique do mouse).
• Só existe um app de pagamento que:
  • Oferece suporte ao identificador da forma de pagamento solicitada.

Quando um app de pagamento baseado na Web é registrado just-in-time (JIT)?

Os apps de pagamento baseados na Web podem ser iniciados sem a visita prévia explícita do usuário ao site do app de pagamento e o registro do service worker. O service worker pode ser registrado em tempo real quando o usuário opta por pagar com o app de pagamento baseado na Web. Há duas variações de tempo de registro:

• Se a interface do Payment Request for mostrada ao usuário, o app será registrado na hora certa e iniciado quando o usuário clicar em Continuar.
• Se a interface do Payment Request for ignorada, o app de pagamento será registrado no momento certo e iniciado diretamente. Ignorar a interface de solicitação de pagamento para iniciar um app registrado em tempo real requer um gesto do usuário, o que impede o registro inesperado de service workers de origem cruzada.

Próximas etapas

Agora que seu app de pagamento está detectável, aprenda a desenvolver um app de pagamento específico para a plataforma e um app de pagamento baseado na Web.

• Apps de pagamento para Android: guia para desenvolvedores
• Guia para desenvolvedores sobre apps de pagamento baseados na Web