Agradecemos por acompanhar o Google I/O. Assista ao conteúdo sob demanda.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Como configurar uma forma de pagamento

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

Eiji Kitamura

Publicado em: 27 de setembro de 2017, última atualização: 16 de outubro de 2026

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 querem se integrar a um app de pagamento vão usar o identificador da forma de pagamento para indicar isso ao navegador. Neste artigo, discutimos como funciona a descoberta de apps de pagamento e como configurar seu app de pagamento para ser descoberto e invocado corretamente por um navegador.

Se você não conhece os pagamentos na Web, leia primeiro a visão geral dos pagamentos na Web.

Tipos de apps de pagamento

Uma forma de pagamento pode ser aceita por um app de pagamento para Android, um app de pagamento baseado na Web ou ambos:

App de pagamento para Android:um app instalado que o Chrome inicia com uma intent do Android. O Chrome verifica o nome do pacote e o certificado de assinatura do app.
App de pagamento baseado na Web:um service worker que o Chrome inicia em uma janela modal. Os usuários não precisam instalar nada.

Os apps de pagamento do Android estão disponíveis no Chrome para Android e no WebView. Os apps de pagamento baseados na Web estão disponíveis no Chrome em todas as plataformas, mas não no WebView.

Se os dois tipos de app estiverem disponíveis para uma forma de pagamento e o manifesto do app da Web definir prefer_related_applications como true, o Chrome vai ocultar o app de pagamento baseado na Web. Caso contrário, os usuários poderão ver os dois na interface da Payment Request e escolher entre eles.

Suporte ao navegador

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

	Chromium		Safari		Firefox
	Computador	Android	Computador	Dispositivo móvel	Computador/dispositivo móvel
API Payment Request	✔	✔	✔	✔
API Payment Handler baseada na Web	✔	✔
App de pagamento para iOS/Android	✔	✔	✔*	✔*

Como um navegador descobre um app de pagamento

Todo app de pagamento precisa fornecer o seguinte:

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

Diagrama: como um navegador descobre o app de pagamento usando um identificador de forma de pagamento baseado em URL

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

O navegador envia uma solicitação ao URL do identificador da forma de pagamento e busca o manifesto da forma de pagamento.
O navegador determina o URL do manifesto do app da Web com base no manifesto da forma de pagamento e busca o manifesto do app da Web.
O navegador determina se o app de pagamento do SO ou o app de pagamento baseado na Web será iniciado com base no 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 descobri-la.

Etapa 1: fornecer o identificador da forma de pagamento

Um identificador de 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 de forma de pagamento, desde que tenham controle sobre ele e possam exibir conteúdo arbitrário e cabeçalhos HTTP. Neste artigo, vamos usar https://bobbucks.dev/pay como o identificador da forma de pagamento.

Como os comerciantes usam o identificador da forma de pagamento

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

O [comerciante] solicita o pagamento:

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

Etapa 2: disponibilizar o manifesto da forma de pagamento

Um manifesto de 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 HEAD para o URL do identificador da forma de pagamento. O URL do identificador da forma de pagamento responde com um cabeçalho HTTP Link que aponta para o URL em que o navegador pode buscar o manifesto da forma de pagamento.

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/pay/payment-manifest.json, o cabeçalho de resposta vai incluir:

Link: <https://bobbucks.dev/pay/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 para ver um exemplo de tráfego de rede. Também é possível usar um comando curl:

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

Em seguida, o navegador envia uma solicitação HTTP GET para o URL do manifesto da forma de pagamento. O servidor responde com o corpo do manifesto da forma de pagamento.

Um manifesto de forma de pagamento tem dois campos: default_applications e supported_origins.

Campos do manifesto da forma de pagamento
Nome da propriedade	Descrição
`default_applications` (obrigatório)	Uma matriz de URLs que aponta para manifestos de apps da Web em que os apps de pagamento estão hospedados. O URL pode ser relativo. Essa matriz precisa fazer referência ao manifesto de desenvolvimento, ao manifesto de produção etc.
`supported_origins`	Uma matriz de URLs que aponta para origens que podem hospedar apps de pagamento de terceiros que implementam a mesma forma de pagamento. Uma forma de pagamento pode ser implementada por vários apps de pagamento.

Um arquivo de manifesto de forma de pagamento deve ser assim:

[payment handler] /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.

Etapa 3: disponibilizar um manifesto do app da Web

Um manifesto do app da Web é usado para definir um app da Web, como o nome sugere. É um arquivo de manifesto amplamente usado para definir um App Web Progressivo (PWA).

Um manifesto típico de app da Web é assim:

[payment handler] /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
  },
  "payment": {
    "supported_delegations": ["shippingAddress", "payerName", "payerEmail", "payerPhone"]
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "prefer_related_applications": true,
  "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"
        }
      ]
    }
  ]
}

O Chrome lê campos diferentes dependendo do tipo de app de pagamento. Para um app de pagamento Android, o Chrome lê apenas related_applications. Para um app de pagamento baseado na Web, o Chrome lê name, icons, serviceworker, payment e prefer_related_applications.

Campos importantes do manifesto do app da Web
Nome da propriedade	Descrição
`name` (obrigatório)	Usado como o nome do app de pagamento.
`icons` (obrigatório)	Usado como o ícone do app de pagamento. Somente o Chrome usa esses ícones. Outros navegadores podem usá-los como ícones substitutos se você não os especificar como parte do instrumento de pagamento.
`serviceworker`	Somente apps de pagamento baseados na Web. Define o service worker que é executado como o app de pagamento.
`serviceworker.src`	O URL para fazer o download do script do service worker.
`serviceworker.scope`	Uma string que representa um URL que define o escopo de registro de um service worker.
`serviceworker.use_cache`	Se o navegador pode usar o cache HTTP ao buscar o script do service worker.
`payment.supported_delegations`	Somente apps de pagamento baseados na Web. As informações de frete e contato que o app de pagamento pode fornecer: `shippingAddress`, `payerName`, `payerEmail` ou `payerPhone`. Os apps de pagamento para Android declaram isso em `AndroidManifest.xml`.
`related_applications`	Somente apps de pagamento para Android. Identifica o app e o certificado de assinatura dele. Saiba mais detalhes no guia para desenvolvedores de apps de pagamento do Android.
`prefer_related_applications`	Defina como `true` para ocultar o app de pagamento baseado na Web quando o app de pagamento Android estiver instalado.

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 abrir

Como 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 correspondem, enquanto a versão mínima (min_version) no manifesto do app da Web é menor ou igual à versão do aplicativo instalado.
O app de pagamento específico da plataforma está instalado e tem:
- Um filtro de intent de org.chromium.intent.action.PAY.
- Um identificador de forma de pagamento especificado como o valor da propriedade org.chromium.default_payment_method_name.

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

[payment handler] /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 prefer_related_applications for true e o app de pagamento específico da plataforma estiver disponível, o Chrome vai ocultar o app de pagamento baseado na Web. Caso contrário, o Chrome também vai procurar o app de pagamento baseado na Web.

Como 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.

[payment handler] /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. Pode ser registrado de forma imediata.

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

Como os navegadores podem pular a interface da API Payment Request e iniciar um app de pagamento diretamente

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

A IU da solicitação de pagamento intervém antes de iniciar o app de pagamento.

Mostrar a IU da Payment Request antes de iniciar um app de pagamento aumenta o número de etapas necessárias para que um usuário conclua 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 da Payment Request quando show() é chamado.

Pule a interface da API Payment Request e inicie o app de pagamento diretamente.

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

show() é acionado com uma interação inicial (por exemplo, um clique do mouse).
Há apenas um app de pagamento que:
- Oferece suporte ao identificador da forma de pagamento solicitada.
- Oferece suporte a todas as informações de frete e contato solicitadas pelo comerciante.

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

Os apps de pagamento baseados na Web podem ser iniciados sem que o usuário tenha visitado explicitamente o site do app de pagamento e registrado o service worker. O service worker pode ser registrado no momento em que o usuário escolhe pagar com o app de pagamento baseado na Web. Há duas variações para o momento do registro:

Se a interface da Payment Request for mostrada ao usuário, o app será registrado just-in-time e iniciado quando o usuário clicar em Continuar.
Se a interface da Payment Request for ignorada, o app de pagamento será registrado just-in-time e iniciado diretamente. Para pular a interface da API Payment Request e iniciar um app registrado just-in-time, é necessário um gesto do usuário, o que impede o registro inesperado de service workers de origem cruzada.

Criar um app de pagamento baseado na Web

Quando o comerciante chama show(), o Chrome envia um evento paymentrequest para seu service worker. Chame openWindow() em respondWith() para mostrar a interface de pagamento e, em seguida, resolva com a resposta de pagamento.

Para ver a API completa, consulte a API Payment Handler baseada na Web no MDN.